Browser script for recording referrals to a website client-side
npm install @ivcmedia/referral-trackerreferral-trackerA 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.
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()mostRecentReferral()
and methods.
Where referrals() returns an array of all recorded referrals andmostRecentReferral() 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 thelandingPageUrl
visitor's browser at that time), is the URL where the referralreferrer
was recorded, is the URL of the referring website (if any), andadCampaign is the ad campaign parameters (e.g. Google UTM\_\* parameters) found
at the time of referral.
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!).