@ivcmedia/referral-tracker

referral-tracker

A zero-dependency browser script that persists referral information in localStorage, allowing other scripts on the page to access that information and use it to attribute actions users take to particular referrals.

Usage

To use, simply include referral-tracker.js in your website's head tag to expose the global ReferralTracker constructor. Then, construct a new tracker instance (preferably in the head):

const referralTracker = new ReferralTracker();

Upon construction the ReferralTracker instance will check to see if the current browser has a previous referral that is still valid. Otherwise it will record a new referral.

interface ReferralTracker {
    constructor(options?: Options);

    referrals(): ReferralInfo[];

    mostRecentReferral(): ReferralInfo | null;
}

interface Options {
    namespace?: string;
    sessionTimeout?: number;
}

To access referral info from the tracker in other scripts, use the referrals() and mostRecentReferral() methods.

Where referrals() returns an array of all recorded referrals and mostRecentReferral() returns the most recent referral, if one exists.

ReferralInfo is an object with information about each referral for the current browser, and contains the following fields:

interface ReferralInfo {
    happenedAt: number;
    landingPageUrl: string;
    referrer?: string;
    adCampaign?: AdCampaign;
}

interface AdCampaign {
    name?: string;
    source?: string;
    medium?: string;
    term?: string;
    content?: string;
}

happenedAt is the timestamp at which the referral happened (as recorded by the visitor's browser at that time), landingPageUrl is the URL where the referral was recorded, referrer is the URL of the referring website (if any), and adCampaign is the ad campaign parameters (e.g. Google UTM_* parameters) found at the time of referral.

Example

A common use case is to include ad-campaign parameters in form submissions so that individual submissions can be attributed to an ad-campaign. Doing that with ReferralTracker is trivial:

const referralTracker = new ReferralTracker();

const mostRecentReferral = referralTracker.mostRecentReferral();
if (mostRecentReferral && mostRecentReferral.adCampaign) {
    document.querySelectorAll("form[data-track-referral]").forEach(form => {
        ["name", "source", "medium", "term", "content"].forEach(fieldName => {
            const value = mostRecentReferral.adCampaign[fieldName] || "none";
            const inputElem = document.createElement("input");
            inputElem.type = "hidden";
            inputElem.name = "adcampaign_" + fieldName;
            inputElem.value = value;
            form.appendChild(inputElem);
        });
    });
}

Now, all forms with a data-track-referral attribute will automatically have hidden fields for each ad-campaign parameter appended to them and included with each submission (make sure your form submission handler is expecting these extra fields though!).