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):

``typescript
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.

`typescript
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:

`typescript
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:

`js
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!).