Refport Docs

refport-js captures the refp_id click ID from the URL and persists it in a cookie for server-side attribution.

refport-js is a tiny, framework-agnostic browser library that handles the first step of referral tracking: reading the refp_id parameter from the landing URL and storing it in a cookie so it's available throughout the session.

Manual installation

Add the browser tracker to the <head> of your site when you want a no-build, framework-agnostic install:

<script
  src="https://cdn.jsdelivr.net/npm/refport-js@0.4.0/dist/auto.iife.js"
  defer
  data-query-param="refp_id"
  data-cookie-name="refp_id"
></script>

The script runs automatically, captures refp_id from the landing URL, stores it in a first-party cookie, and exposes window._refport for verification.

For shared cookies across subdomains, add a cookie domain:

Use a leading dot for shared attribution cookies: .example.com, not example.com. This is the setting to use when visitors can move between example.com and app.example.com before converting.

<script
  src="https://cdn.jsdelivr.net/npm/refport-js@0.4.0/dist/auto.iife.js"
  defer
  data-query-param="refp_id"
  data-cookie-name="refp_id"
  data-cookie-domain=".yoursite.com"
></script>

Verify the install by opening your site with ?refp_id=test, checking window._refport in the browser console, and confirming the refp_id cookie exists.

Script attributes

Attribute	Description
`data-query-param`	URL query parameter to capture
`data-query-params`	JSON array or comma-separated query parameters
`data-cookie-name`	Cookie name
`data-cookie-domain`	Cookie domain, such as `.yoursite.com`
`data-cookie-path`	Cookie path
`data-max-age`	Cookie max age in seconds
`data-same-site`	Cookie SameSite value: `Strict`, `Lax`, or `None`
`data-secure`	Set to `true` or `false` to override the Secure flag
`data-clean-url`	Set to `false` to keep the query parameter in the URL
`data-cookie-options`	JSON object with cookie options like `expiresInDays`

Bundler installation

npm install refport-js
# or
pnpm add refport-js
# or
yarn add refport-js

Usage

`init(options?)`

Call init() once when your app loads. It checks the current URL for a refp_id query parameter, writes it to a cookie if found, and optionally cleans the parameter from the URL.

import { init } from "refport-js";

const result = init();
console.log(result.clickId); // the captured (or existing) click ID, or null

If a cookie already exists (return visit), init() returns it without overwriting.

`getClickId(cookieName?)`

Reads the current click ID from the cookie without triggering any side-effects. Useful in components that need the click ID after init() has already run.

import { getClickId } from "refport-js";

const clickId = getClickId(); // string | null

`reset(options?)`

Deletes the tracking cookie. Call this after a successful lead or sale event if you want to clear attribution state.

import { reset } from "refport-js";

reset();

Return value of `init()`

init() returns a RefportTrackingResult object:

Field	Type	Description
`tracked`	`boolean`	`true` if a new click ID was captured from the URL
`clickId`	`string \| null`	The active click ID (from URL or existing cookie)
`source`	`"url" \| "cookie" \| null`	Where the click ID came from

Options

All options are optional. Defaults match Refport's server-side expectations.

Option	Type	Default	Description
`cookieName`	`string`	`"refp_id"`	Cookie name to read/write
`paramName`	`string`	`"refp_id"`	URL query parameter name to look for
`maxAge`	`number`	`7776000` (90 days)	Cookie lifetime in seconds
`path`	`string`	`"/"`	Cookie path
`domain`	`string`	—	Cookie domain (e.g. `.yoursite.com` for subdomain sharing)
`sameSite`	`"Strict" \| "Lax" \| "None"`	`"Lax"`	SameSite cookie attribute
`secure`	`boolean`	auto-detected	Sets the `Secure` flag; defaults to `true` on HTTPS
`cleanUrl`	`boolean`	`true`	Remove `refp_id` from the browser URL after capture

Example with custom domain

If your app spans multiple subdomains (e.g. www.yoursite.com and app.yoursite.com), share the cookie across all of them:

init({ domain: ".yoursite.com" });

Keep the leading . in production, for example .example.com, so the tracking cookie is shared across the apex domain and subdomains.

TypeScript types

import type { RefportTrackingOptions, RefportTrackingResult } from "refport-js";

JavaScript (Browser)