@guardian/ophan-tracker-js 4.0.2 → 5.0.0

package/src/transmit.ts

@@ -0,0 +1,176 @@
+import { EventPayload } from './types/event.js';
+
+const canSendFromCurrentRuntime = (): boolean =>
+	typeof window !== 'undefined' && typeof document !== 'undefined';
+
+// Initialize ophanRemoteHost when needed, not at module load
+let ophanRemoteHost: string;
+const getOphanRemoteHost = (): string => {
+	if (!ophanRemoteHost) {
+		ophanRemoteHost =
+			typeof window !== 'undefined' && (window as any)?.ophanRemoteHost
+				? (window as any).ophanRemoteHost
+				: 'https://ophan.theguardian.com';
+	}
+	return ophanRemoteHost;
+};
+
+/**
+ * Generates a unique page view ID.
+ * @returns {string}
+ */
+const generatePageViewId = (): string => {
+	return `${new Date().getTime().toString(36)}${'xxxxxxxxxxxx'.replace(
+		/x/g,
+		() => Math.floor(Math.random() * 36).toString(36),
+	)}`;
+};
+
+declare const guardian: any;
+
+// Guardian Frontend Project pre-generates the pageViewId
+let viewId: string;
+if (typeof guardian !== 'undefined') {
+	viewId = guardian.config?.ophan?.pageViewId ?? generatePageViewId();
+} else {
+	viewId = generatePageViewId();
+}
+
+const bumpViewId = (): void => {
+	const viewIdGen = generatePageViewId();
+	viewId = viewIdGen;
+
+	if (typeof guardian !== 'undefined' && guardian.config?.ophan) {
+		guardian.config.ophan.pageViewId = viewIdGen;
+	}
+};
+
+/**
+ * Sends the initial event associated with this page view.
+ * @param {Record<string, any>} obj - The data to be sent.
+ */
+const sendInitial = (obj: Record<string, any>): void => {
+	send(`${getOphanRemoteHost()}/img/1?${buildQueryString(obj)}`);
+};
+
+/**
+ * Encodes a value for URL transmission.
+ * @param {string | number} value - The value to encode.
+ * @returns {string} The encoded value.
+ */
+const smartEncode = (value: string | number): string => {
+	if (typeof value === 'string' || typeof value === 'number') {
+		return encodeURIComponent(value);
+	} else {
+		return encodeURIComponent(JSON.stringify(value));
+	}
+};
+
+/**
+ * Used for sending additional events after the initial PageView event.
+ * @param {EventPayload} obj - The data object to be sent.
+ * @param {Function} [f] - An optional callback function.
+ */
+const sendMore = (obj: EventPayload, f?: () => void): void => {
+	if (!JSON) return;
+
+	const values: string[] = [];
+	for (const prop in obj) {
+		// @ts-ignore
+		if (obj.hasOwnProperty(prop) && isDefined(obj[prop])) {
+			// @ts-ignore
+			values.push(`${encodeURIComponent(prop)}=${smartEncode(obj[prop])}`);
+		}
+	}
+
+	if (values.length === 0) {
+		return;
+	}
+
+	const url = `${getOphanRemoteHost()}/img/2?viewId=${viewId}&${values.join('&')}`;
+	send(url, f);
+};
+
+/**
+ * Checks if a value is defined and not null.
+ * @param {*} v - The value to check.
+ * @returns {boolean} True if the value is defined, false otherwise.
+ */
+const isDefined = (v: any): boolean => {
+	if (Array.isArray(v)) {
+		return !!v.length;
+	} else {
+		return v != null;
+	}
+};
+
+/**
+ * Builds a query string from an object.
+ * @param {Record<string, any>} obj - The object to convert to a query string.
+ * @returns {string} The resulting query string.
+ */
+const buildQueryString = (obj: Record<string, any>): string => {
+	obj.viewId = viewId;
+
+	const values: string[] = [];
+	for (const prop in obj) {
+		if (obj.hasOwnProperty(prop) && obj[prop] != null) {
+			values.push(
+				`${encodeURIComponent(prop)}=${encodeURIComponent(obj[prop])}`,
+			);
+		}
+	}
+
+	return values.join('&');
+};
+
+/**
+ * Sends data to a specified URL.
+ * @param {string} url - The URL to send data to.
+ * @param {() => void} [f] - An optional callback function.
+ */
+const send = (url: string, f?: () => void): void => {
+	if (!canSendFromCurrentRuntime()) {
+		f?.();
+		return;
+	}
+
+	if (typeof fetch === 'function') {
+		fetch(url, {
+			method: 'GET',
+			mode: 'no-cors',
+			keepalive: true,
+			credentials: 'include',
+		}).then(() => f?.());
+	} else {
+		const image = new Image();
+		const checker = setInterval(() => {
+			if (image.complete) {
+				if (typeof f === 'function') {
+					f();
+				}
+				clearInterval(checker);
+			}
+		}, 10);
+		image.src = url;
+	}
+};
+
+export default {
+	sendInitial,
+	sendMore,
+	get viewId() {
+		return viewId;
+	},
+	bumpViewId,
+};
+
+/**
+ * Exports for testing purposes.
+ */
+export const _testExports = {
+	generatePageViewId,
+	smartEncode,
+	isDefined,
+	buildQueryString,
+};

package/src/types/abtest.ts

@@ -0,0 +1,45 @@
+/**
+ * Represents the AbTest on the web and apps
+ */
+export interface AbTest {
+  /**
+   * the test that the user is participating in
+   */
+  name: string;
+
+  /**
+   * the variant that they are seeing
+   */
+  variant: string;
+
+  /**
+   * whether the test has been completed or not
+   */
+  complete?: boolean;
+
+  /**
+   * the campaign codes associated with the variant
+   */
+  campaignCodes?: Array<string>;
+}
+
+export interface AbTestRegisterEntry {
+  /**
+   * Variant assigned to the user for this test
+   */
+  variantName: string;
+
+  /**
+   * Whether this test has completed for the user
+   */
+  complete: boolean;
+
+  /**
+   * Campaign codes associated with this variant
+   */
+  campaignCodes?: Array<string>;
+}
+
+export type AbTestRegisterValue = AbTestRegisterEntry | string;
+
+export type AbTestRegister = Record<string, AbTestRegisterValue>;

package/src/types/component-event.ts

@@ -0,0 +1,121 @@
+import type { AbTest } from './abtest.js';
+import type { Product } from './product.js';
+import { TComponentType } from './component-type.js';
+
+/** User or lifecycle action observed for a tracked component. */
+export type TAction =
+	/**
+	 * The component was inserted into its container (e.g. a web page or view in an app)
+	 **/
+	| 'INSERT'
+
+	/**
+	 * The component was in view on screen
+	 **/
+	| 'VIEW'
+
+	/**
+	 * The component was expanded (e.g. "see more").
+	 * Not a navigation away to another page
+	 **/
+	| 'EXPAND'
+
+	/**
+	 * A "like", thumbs up, etc.
+	 **/
+	| 'LIKE'
+
+	/**
+	 * A "dislike", thumbs down, etc.
+	 **/
+	| 'DISLIKE'
+
+	/**
+	 * A subscription to a service, newsletter, etc.
+	 **/
+	| 'SUBSCRIBE'
+
+	/**
+	 * Selection of an answer in a quiz
+	 **/
+	| 'ANSWER'
+
+	/**
+	 * A vote in a poll
+	 **/
+	| 'VOTE'
+
+	/**
+	 * A single click on the component which is not covered by
+	 * any of the existing Actions.
+	 **/
+	| 'CLICK'
+
+	/**
+	 * User sign in to Guardian Identity account
+	 **/
+	| 'SIGN_IN'
+
+	/**
+	 * User creates a Guardian Identity account
+	 **/
+	| 'CREATE_ACCOUNT'
+
+	/**
+	 * User Consent
+	 **/
+	| 'ACCEPT_DEFAULT_CONSENT'
+	| 'MANAGE_CONSENT'
+	| 'CONSENT_ACCEPT_ALL'
+	| 'CONSENT_REJECT_ALL'
+	| 'CONSENT_GEOLOCATION_MISMATCH'
+
+	/**
+	 * The component sticks in the screen
+	 **/
+	| 'STICK'
+
+	/**
+	 * The component is closed
+	 **/
+	| 'CLOSE'
+
+	/**
+	 * The component is returned to its original location
+	 **/
+	| 'RETURN'
+
+	/**
+	 * The component has detected something
+	 */
+	| 'DETECT';
+
+/** Component metadata attached to a `ComponentEvent`. */
+interface ComponentV2 {
+	/** Stable type describing the product/UI area that owns the component. */
+	componentType: TComponentType;
+	/** Optional caller-defined identifier for this component instance. */
+	id?: string;
+	/** Guardian products associated with the component, usually for acquisition flows. */
+	products?: Array<Product>;
+	/** Campaign code associated with the component. */
+	campaignCode?: string;
+	/** Free-form labels used for downstream grouping and analysis. */
+	labels?: Array<string>;
+}
+
+/** Event generated by a component interaction or component lifecycle change. */
+export interface ComponentEvent {
+	/** Component metadata describing what was interacted with. */
+	component: ComponentV2;
+	/** Action the user or component performed. */
+	action: TAction;
+	/** Optional action-specific value, such as a quiz answer or poll choice. */
+	value?: string;
+	/** Optional caller-defined identifier for this event. */
+	id?: string;
+	/** A/B test context for the component. */
+	abTest?: AbTest;
+	/** A/B test context used for targeting the component. */
+	targetingAbTest?: AbTest;
+}

package/src/types/component-type.ts

@@ -0,0 +1,70 @@
+/**
+ * Stable component category used by Ophan component events.
+ *
+ * Choose the closest existing value before adding a new one; these values are
+ * consumed downstream for reporting and analysis.
+ */
+export type TComponentType =
+	| 'READERS_QUESTIONS_ATOM'
+	| 'QANDA_ATOM'
+	| 'PROFILE_ATOM'
+	| 'GUIDE_ATOM'
+	| 'TIMELINE_ATOM'
+	| 'NEWSLETTER_SUBSCRIPTION'
+	| 'SURVEYS_QUESTIONS'
+	| 'ACQUISITIONS_EPIC'
+	| 'ACQUISITIONS_ENGAGEMENT_BANNER'
+	| 'ACQUISITIONS_THANK_YOU_EPIC'
+	| 'ACQUISITIONS_HEADER'
+	| 'ACQUISITIONS_FOOTER'
+	| 'ACQUISITIONS_INTERACTIVE_SLICE'
+	| 'ACQUISITIONS_NUGGET'
+	| 'ACQUISITIONS_STANDFIRST'
+	| 'ACQUISITIONS_THRASHER'
+	| 'ACQUISITIONS_EDITORIAL_LINK'
+	| 'ACQUISITIONS_MANAGE_MY_ACCOUNT'
+	| 'ACQUISITIONS_BUTTON'
+	| 'ACQUISITIONS_OTHER'
+	| 'APP_ADVERT'
+	| 'APP_AUDIO'
+	| 'APP_BUTTON'
+	| 'APP_CARD'
+	| 'APP_CROSSWORDS'
+	| 'APP_ENGAGEMENT_BANNER'
+	| 'APP_EPIC'
+	| 'APP_GALLERY'
+	| 'APP_LINK'
+	| 'APP_NAVIGATION_ITEM'
+	| 'APP_SCREEN'
+	| 'APP_THRASHER'
+	| 'APP_VIDEO'
+	| 'AUDIO_ATOM'
+	| 'CHART_ATOM'
+	| 'ACQUISITIONS_MERCHANDISING'
+	| 'ACQUISITIONS_HOUSE_ADS'
+	| 'SIGN_IN_GATE'
+	| 'ACQUISITIONS_SUBSCRIPTIONS_BANNER'
+	| 'MOBILE_STICKY_AD'
+	| 'IDENTITY_AUTHENTICATION'
+	| 'RETENTION_ENGAGEMENT_BANNER'
+	| 'ACQUISITION_SUPPORT_SITE'
+	| 'RETENTION_EPIC'
+	| 'CONSENT'
+	| 'LIVE_BLOG_PINNED_POST'
+	| 'STICKY_VIDEO'
+	| 'KEY_EVENT_CARD'
+	| 'RETENTION_HEADER'
+	| 'SLIDESHOW'
+	| 'APP_FEATURE'
+	| 'CARD'
+	| 'CAROUSEL'
+	| 'CONTAINER'
+	| 'MENU'
+	| 'ACQUISITIONS_GUTTER'
+	| 'INTERACTIVE_ATOM'
+	| 'LOOP_VIDEO'
+	| 'AD_BLOCK_RECOVERY'
+	| 'SIGN_IN_GOOGLE_ONE_TAP'
+	| 'BF_CACHE'
+	| 'AFFILIATE_DISCLAIMER'
+	| 'STORYLINES';

package/src/types/consent.ts

@@ -0,0 +1,49 @@
+/** A user’s recorded tracking consent. Because the consent data can come in
+ * different formats from different sources, the jurisdiction field determines
+ * the format of consentData.
+ **/
+export interface Consent {
+    /**
+     * The jurisdiction is a tag for the consent data: TCF, CCPA, or AUS if the
+     * consent has been successfully parsed in one of those formats; or
+     * OTHER otherwise.
+     **/
+    consentJurisdiction: TJurisdiction;
+
+    /**
+     * If the jurisdiction is TCF, CCPA, or AUS, consentData contains a
+     * successfully interpreted consent value the corresponding type (for TCF
+     * this is a base-64-encoded consent string, and for CCPA and AUS it’s
+     * either the string "true" or "false" – where "true" means the user has
+     * given their consent). If the jurisdiction is OTHER, then consentData
+     * contains the unparsed consent data, in the format
+     * key1:value1,key2:value2,….
+     **/
+    consent: string;
+
+    /**
+     * consentUUID is an identifier for the consent, for debugging.
+     **/
+    consentUUID?: string;
+
+    /**
+     * cmp version for debugging
+     **/
+    cmpVersion?: string;
+}
+
+/**
+ * For a recognised/successfully parsed consent, a value of TCF, USNAT, CCPA, or AUS
+ * indicates which jurisdiction the consent is for. OTHER marks a consent
+ * that was not successfully parsed into one of these formats.
+ *
+ * - TCF is Europe’s [Transparency & Consent Framework](https://iabeurope.eu/transparency-consent-framework/).
+ * - CCPA is the [California Consumer Privacy Act](https://oag.ca.gov/privacy/ccpa). This has now been deprecated and replaced by USNAT: https://github.com/guardian/ophan/pull/5974
+ * - AUS is for Australian consents, using a version of the CCPA.
+ **/
+export type TJurisdiction =
+    | "TCF"
+    | "USNAT"
+    | "CCPA"
+    | "AUS"
+    | "OTHER";

package/src/types/event.ts

@@ -0,0 +1,116 @@
+import type { AbTestRegister } from './abtest.js';
+import type { ComponentEvent } from './component-event.js';
+import type { Consent } from './consent.js';
+import type { InPageClick } from './inpageclick.js';
+import { Interaction } from './interaction.js';
+import type { AudioEvent, VideoEvent } from './media.js';
+import type { TPlatform } from './platform.js';
+import type { TMembershipTier, TSubscriptionType } from './subscription.js';
+
+/**
+ * Details about a page view - only populated for _PAGE_VIEW
+ * event types
+ **/
+interface PageView {
+	/** Url of the page served */
+	url: string;
+	/** The platform that served this page */
+	platform?: TPlatform;
+	/** Some approximation of the content type */
+	contentType?: string;
+	/** URL of the referrer to this page view */
+	ref?: string;
+	/** The number of days in the previous week that the device has had a page view */
+	daysVisitedInLastWeek?: number;
+	/** Total number of days on which this browser has visited the guardian */
+	totalDaysVisited?: number;
+	/** Calculated average days between recent visits */
+	averageDaysBetweenRecentVisits?: number;
+	/** No longer used in Ophan. Replaced by Frequency */
+	regular?: boolean;
+	subscriptionType?: TSubscriptionType;
+	membershipTier?: TMembershipTier;
+	navigationType?: PerformanceNavigationTiming['type'];
+	/** The type of page load - normal or from cache */
+	loadType?: 'normal' | 'bfcache';
+	from?: string;
+	to?: string;
+	tz?: string;
+	visibilityState?: string;
+}
+
+interface AssetPerformanceData {
+	/** The name of the metric being captured */
+	name: string;
+	/** Value of window.performance.now at which metric was captured */
+	timing: number;
+}
+
+interface WebPerformanceData {
+	/** Time in ms that dns lookup took */
+	dns: number;
+	/** Time in ms that connection to the server took */
+	connection: number;
+	/** Time to first byte */
+	firstByte: number;
+	/** First byte to last byte */
+	lastByte: number;
+	/** From last byte of doc to start of domContentLoaded */
+	domContentLoadedEvent: number;
+	/** domContentLoaded to start of load event */
+	loadEvent: number;
+	/** The navigation type */
+	navType: number;
+	/** Number of redirects on current domain */
+	redirectCount: number;
+	/** List of custom Asset performance data */
+	assetsPerformance?: AssetPerformanceData[];
+}
+
+interface Component {
+	/** The name of this component */
+	name: string;
+	/** How long, in milliseconds, that the component took to load */
+	loadTimeMs?: number;
+}
+
+interface LazyComponents {
+	/** The set of components that were loaded lazily on this page */
+	components: Component[];
+}
+
+/** Guardian edition associated with a page view or event. */
+export type TEdition = 'UK' | 'US' | 'AU' | 'International' | 'Europe';
+
+/**
+ * Payload accepted by `record()`.
+ *
+ * Each property maps to an Ophan event field. Most calls set one focused event
+ * shape, such as `componentEvent`, `interaction`, `audio`, or `video`, plus any
+ * supporting metadata such as `edition`.
+ */
+export interface EventPayload extends Partial<Consent>, Partial<InPageClick> {
+	/** If the user is logged in, the identity user id */
+	userId?: string;
+	/** Page-view details. Usually sent by tracker initialisation rather than application code. */
+	pageView?: PageView;
+	/** Attention time spent on this page view in milliseconds */
+	attentionMs?: number;
+	/** Map of component name to time in ms */
+	componentAttentionMs?: { [key: string]: number };
+	performance?: WebPerformanceData;
+	audio?: AudioEvent;
+	video?: VideoEvent;
+	abTestRegister?: AbTestRegister;
+	lazyComponents?: LazyComponents;
+	interaction?: Interaction;
+	inPrivateBrowsingMode?: boolean;
+	adUnitWasHidden?: boolean;
+	/** Component interaction, render, consent, or acquisition event. */
+	componentEvent?: ComponentEvent;
+	/** Experience contains information about the rendering of the page, e.g.: dotcom-rendering */
+	experiences?: Array<string>;
+	edition?: TEdition;
+	/** The set of component names that were rendered on this page, e.g.: ["nav3","nav2","sub-nav","footer"] */
+	renderedComponents?: Array<string>;
+}

package/src/types/inpageclick.ts

@@ -0,0 +1,13 @@
+import { LinkName } from './link.js';
+
+export interface InPageClick {
+	/**
+	 * the component that contained the item clicked on
+	 */
+	clickComponent?: string;
+
+	/**
+	 * The link name associated with the element clicked.
+	 */
+	clickLinkNames?: LinkName;
+}

package/src/types/interaction.ts

@@ -0,0 +1,19 @@
+/**
+ * Represents an interaction on the web or apps
+ */
+export interface Interaction {
+  /**
+   * Key for the interaction.
+   */
+  component: string;
+
+  /**
+   * Value associated with the interaction
+   */
+  value?: string;
+
+  /**
+   * The id of the atom that the interaction has come from
+   */
+  atomId?: string;
+}

package/src/types/link.ts

@@ -0,0 +1,14 @@
+/**
+ * Represents the position and location of a link within the Guardian site.
+ * We hope to enhance this structure to include a better representation of what the links
+ * actually mean, but for now we just report exactly what the web site tells us,
+ * which is a hierarchical list of named items e.g.
+ *  "more","container-2 | highlights","Front | /uk"
+ *  "article","news | group-1+ | card-3","container-1 | headlines","Front | /uk"
+ */
+export type LinkName = {
+  /**
+   * List of link names, most specific first
+   */
+  raw?: string[];
+}