JavaScript (Browser)

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.

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:

Options

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

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' });

TypeScript types

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