react-marketing-tools 1.0.0-alpha.4 → 1.0.0-alpha.5

package/README.md

@@ -1,226 +1,89 @@
+# React Marketing Tools
 
-# React Marketing Tools   [![npm version](https://badge.fury.io/js/react-marketing-tools.svg)](https://badge.fury.io/js/react-marketing-tools)
-
-React Marketing Tools are a set of tools to make it easier for you to implement analytics and track user journeys, interactions throughout your App. using dataLayer/Google Tag Manager, GA4 fetch directly or coming soon facebook pixel.
-
-* [React Marketing Tools Demo](https://codepen.io/bronz3beard/pen/yLZmMeg)
-* [Detailed Blog post on React Marketing Tools Implementation](https://blog.heyrory.com/google-analytics-4-google-tag-manager)
-
-
-# PR's
-- Have a look at the [PR template doc](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs) for best approach to getting your pr merged.
-
-# CHANGELOG
-- You can view it [here](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/CHANGELOG.md)
-
-# Usage and setup examples.
-
-### Setup configuration
-- Setting up config without provider is also an option, in this case you will only need to import _buildConfig_
-```js
-    import React from 'react'
-    import ReactDOM from 'react-dom/client'
-    import {
-        ReactMarketingProvider,
-        buildConfig,
-        BuildConfigOptions,
-        Tokens,
-    } from 'react-marketing-tools'
-    import App from './App'
-
-    /*
-        TOKENS are optional
-        const TOKENS: Tokens = {
-
-            // if withServerLocationInfo is true you must supply this token.
-            IP_INFO_TOKEN: 'SOME_TOKEN',
-
-            // if analyticsType = analyticsPlatform.GOOGLE the below tokens must be supplied.
-            GA4_PUBLIC_API_SECRET: 'SOME_TOKEN',
-            GA4_PUBLIC_MEASUREMENT_ID: 'SOME_TOKEN',
-        }
-    */
-
-    // These are the keys for the values you want to include from your user data
-    // these must be included for any user data to be collected by analytics event if user data is hardcoded when passed in.
-    const includeUserKeys = [
-        'firstName',
-        'lastName',
-    ]
-
-    const analyticsConfig: BuildConfigOptions = {
-        appName: 'my-awesome-app', // required
-        appSessionCookieName: 'APP_SESSION',
-        eventActionPrefix: { // this will extend the default values of eventActionPrefix 
-            ACTION: 'ACTION',
-            OTHER_EVENT_NAME_TYPE: 'OTHER_EVENT_NAME_TYPE'
-        },
-        globalEventActionList: { // this will extend the default values of globalEventActionList 
-            SIGN_IN: 'SIGN_IN',
-            SIGN_UP: 'SIGN_UP',
-            IMPORTANT_BUTTON_CLICKED: 'IMPORTANT_BUTTON_CLICKED'
-        },
-        // TOKENS // (optional), 
-        includeUserKeys,
-        showMissingUserAttributesInConsole: false, // a boolean condition to show or hide "user" attributes that are not included in the "includeUserKeys" array, by console logging in dev tools.
-        withDeviceInfo: true, // (optional) has default value
-        withServerLocationInfo: false, // (optional) has default value
-    }
-
-    /**
-        * @type {Object} buildConfig -> options: all attributes of the options object must have a value, other than withDeviceInfo.
-        * @property {string} appName: the name of your app this value must be passed in.
-        * @property {string} appSessionCookieName This is used to get the cookie from storage based on a key you use, the value from the cookie will be used in "client_id:"
-        * @property {Object} eventActionPrefix: is a { key: 'value' } object that allows you to extend "analyticsEventActionPrefixList" object with custom eventActionPrefix. To see the build in list call the function showMeBuildInEventActionPrefixList().
-        * @property {Object} globalEventActionList: is a { key: 'value' } object that allows you to extend "analyticsGlobalEventActionList" object with custom eventActionNames. To see the build in list call the function showMeBuildInGlobalEventActionList().
-        * @property {Array} includeUserKeys: is an array of strings that represent keys from your user data that you want to whitelist, user data you wan to hash.
-        * @property {Boolean} showMissingUserAttributesInConsole a boolean condition to show or hide "user" attributes that are not included in the "includeUserKeys" array, by console logging in dev tools.
-        * @property {Object} TOKENS: is a { key: 'value' } object that includes the following keys, IP_INFO_TOKEN, GA4_PUBLIC_API_SECRET, GA4_PUBLIC_MEASUREMENT_ID, depending on if you need these features enabled.
-        * @property {Boolean} withDeviceInfo: if you want device information added to "globalVars" set this to true false by default.
-        * @property {Boolean} withServerLocationInfo: if you want server information added to "journeyProps" set this to true false by default.
-    */
-    buildConfig(analyticsConfig)
-
-    ReactDOM.createRoot(document.getElementById('root')).render(
-        <React.StrictMode>
-            <ReactMarketingProvider>
-                <App />
-            </ReactMarketingProvider>
-        </React.StrictMode>
-    )
+[![npm next](https://img.shields.io/npm/v/react-marketing-tools/next?label=npm%40next)](https://www.npmjs.com/package/react-marketing-tools?activeTab=versions)
+[![license](https://img.shields.io/npm/l/react-marketing-tools)](./LICENSE)
 
+One `track()` call for Google Tag Manager, Google Analytics 4 and the Meta Pixel, with Consent Mode v2, UTM attribution
+and personal-data redaction built in.
+
+> **1.0 is in alpha** on the `next` tag. `npm install react-marketing-tools` still installs 0.4.x, whose API 1.0
+> replaces; see the [changelog](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/CHANGELOG.md).
+
+## Install
+
+```sh
+npm install react-marketing-tools@next
+```
+
+Requires React 18 or 19. The package is ESM-only; server rendering needs Node.js 22.12 or later.
+
+## Usage
+
+Create one instance:
+
+```ts
+// analytics.ts
+import { createAnalytics } from 'react-marketing-tools'
+
+export const analytics = createAnalytics({
+  consent: 'denied', // until your consent banner records the visitor's choice
+  gtm: { containerId: 'GTM-XXXXXXX' },
+  ga4: { measurementId: 'G-XXXXXXX' },
+  metaPixel: { pixelId: '1234567890123456' },
+})
+```
+
+Provide it to your app:
+
+```tsx
+// main.tsx
+import { AnalyticsProvider } from 'react-marketing-tools'
+import { analytics } from './analytics'
+
+createRoot(document.getElementById('root')!).render(
+  <AnalyticsProvider analytics={analytics}>
+    <App />
+  </AnalyticsProvider>,
+)
 ```
 
-## Usage with Provider
-```js
-    import { useState, useEffect, useCallback, useRef } from 'react'
-    import {
-        useMarketingApi,
-        useMarketingState,
-        EventNameInfo,
-        TrackAnalyticsEventOptions,
-        ProviderApiProps,
-        ProviderStateProps,
-    } from 'react-marketing-tools'
-
-    function App() {
-        const [count, setCount] = useState(0)
-        const {
-            analyticsPlatform,
-            appSessionCookieName,
-            eventActionPrefixList,
-            analyticsGlobalEventActionList,
-        }: ProviderStateProps = useMarketingState()
-        const {
-            trackAnalyticsEvent
-            /*
-                NOTE: If you want to see built in config items and your added items, use one of the following functions to the body of your functional component or useEffect/function
-                call it like so showMeBuildInAnalyticsPlatform() then check your console, in dev tools.
-                showMeBuildInAnalyticsPlatform,
-                showMeBuildInEventActionPrefixList,
-                showMeBuildInGlobalEventActionList,
-            */
-        }: ProviderApiProps = useMarketingApi()
-
-        useEffect(function appLoadPageLandingWelcome() {
-            // create session cookie, useful for unauthenticated user tracking and other things
-            document.cookie = `${appSessionCookieName}=${uuid()};max-age=${70};SameSite=Strict;Secure`
-
-            const sendAnalyticsEvent = async () => {
-                const eventNameInfo: EventNameInfo = {
-                    // If this is not passed in the event name will be a combination of actionPrefix & globalAppEvent
-                    // J_UNAUTHENTICATED
-                    eventName: 'Welcome Landing',
-                    actionPrefix: eventActionPrefixList.JOURNEY,
-                    globalAppEvent: analyticsGlobalEventActionList.UNAUTHENTICATED,
-                }
-
-                const trackingData: TrackAnalyticsEventOptions = {
-                    data: {},
-                    eventNameInfo,
-                    analyticsType: analyticsPlatform.DATALAYER_PUSH,
-                    dataLayerCheck: true,
-                    userDataKeysToHashArray: null,
-                }
-
-                await trackAnalyticsEvent(trackingData)
-            }
-
-            sendAnalyticsEvent()
-        }, [])
-
-        const handleButtonClick = useCallback(async () => {
-            const countActual = count + 1
-            setCount(countActual)
-
-            const eventNameInfo: EventNameInfo = {
-                // If this is not passed in the event name will be a combination of actionPrefix & globalAppEvent
-                // I_AUTHENTICATED
-                eventName: 'count button click',
-                actionPrefix: eventActionPrefixList.INTERACTION,
-                globalAppEvent: analyticsGlobalEventActionList.AUTHENTICATED,
-                previousGlobalAppEvent: analyticsGlobalEventActionList.UNAUTHENTICATED,
-            }
-
-            const trackingData: TrackAnalyticsEventOptions = {
-                data: {
-                    count: countActual,
-                    // firstName: 'bob',
-                    lastName: 'yeah nah',
-                    email: 'yeahnah@gmail.com',
-                },
-                eventNameInfo,
-                analyticsType: analyticsPlatform.DATALAYER_PUSH,
-                consoleLogData: {
-                    showJourneyPropsPayload: true,
-                },
-                dataLayerCheck: false,
-                userDataKeysToHashArray: null,
-            }
-
-            await trackAnalyticsEvent(trackingData)
-        }, [count])
-
-        /* Example: use GA4 directly 
-        const handleButtonClick = useCallback(async () => {
-            const countActual = count + 1
-
-            setCount(countActual)
-
-            const eventNameInfo: EventNameInfo = {
-                eventName: 'count button click',
-                actionPrefix: eventActionPrefixList.INTERACTION,
-                globalAppEvent: analyticsGlobalEventActionList.AUTHENTICATED,
-                previousGlobalAppEvent: analyticsGlobalEventActionList.UNAUTHENTICATED,
-            }
-
-            const trackingData: TrackAnalyticsEventOptions = {
-                data: {
-                    count: countActual,
-                    firstName: 'bob',
-                    lastName: 'yeah nah',
-                    email: 'yeahnah@gmail.com',
-                },
-                eventNameInfo,
-                analyticsType: analyticsPlatform.GOOGLE,
-                userDataKeysToHashArray: ['email', 'firstName', 'lastName'],
-                consoleLogData: {
-                    showJourneyPropsPayload: true,
-                },
-            }
-
-            await trackAnalyticsEvent(trackingData)
-        }, [count])
-        */
-
-        ...
-
-        return (
-            ...
-        )
-    }
+Track from any component:
+
+```tsx
+import { useAnalytics } from 'react-marketing-tools'
 
+export const SignUpButton = () => {
+  const { track } = useAnalytics()
+
+  // Reaches GTM, GA4 and Meta (as CompleteRegistration) with one shared event_id
+  return <button onClick={() => track('sign_up', { method: 'google' })}>Sign up</button>
+}
 ```
 
-## Usage without Provider
-> To view implementation and usage without the React Context/Provider visit this [codepen](https://codepen.io/roryfn/pen/OJBGvMG)
+The same instance identifies users and records consent:
+
+```ts
+analytics.identify('user-42', { email: 'ada@example.com' }) // user id for GTM and GA4, advanced matching for Meta
+analytics.consent.update({ analytics: 'granted', ads: 'granted' }) // Google Consent Mode v2 and Meta consent
+```
+
+Configure only the destinations you use. Without React, import `createAnalytics` from `react-marketing-tools/core` and
+call `analytics.start()` yourself.
+
+## Documentation
+
+- [Getting started](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/getting-started.md)
+- [React](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/react.md): provider, hook, Next.js App Router, single-page apps
+- [Tracking events](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/tracking-events.md): naming rules, page views, users, personal data, errors
+- [Configuration](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/configuration.md)
+- [Consent](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/consent.md): Consent Mode v2 and Global Privacy Control
+- [Attribution](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/attribution-utm.md): UTM params and ad click IDs
+- [Google Tag Manager](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/google-tag-manager.md)
+- [Google Analytics 4](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/google-analytics-4.md)
+- [Meta Pixel](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/meta-pixel.md)
+- [Server-side tagging](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/server-side-tagging.md)
+- [Changelog](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/CHANGELOG.md)
+
+## License
+
+[MIT](./LICENSE)

package/dist/attribution/attribution.d.ts

@@ -0,0 +1,21 @@
+import type { Attribution, CampaignParam } from '../core/types.js';
+export declare const CAMPAIGN_PARAMS: readonly CampaignParam[];
+/**
+ * The campaign behind a visit, from its landing URL. `undefined` when the URL carries no campaign params, so a plain
+ * navigation never replaces an earlier touch. Values are email-redacted (email tools put addresses in `utm_term`).
+ */
+export declare const parseAttribution: ({ url, referrer, capturedAt, }: {
+    url: string;
+    referrer?: string;
+    capturedAt: number;
+}) => Attribution | undefined;
+/** Stored attribution is untrusted input: anything that isn't a well-formed touch is discarded. */
+export declare const toAttribution: (value: unknown) => Attribution | undefined;
+/**
+ * Meta's click ID for the Conversions API: the Pixel's `_fbc` cookie as-is (Meta may append to it), otherwise built from
+ * the touch's `fbclid` in Meta's documented `fb.1.<creation time ms>.<fbclid>` format.
+ */
+export declare const deriveFbc: ({ fbcCookie, touch, }: {
+    fbcCookie?: string;
+    touch?: Attribution;
+}) => string | undefined;

package/dist/attribution/tracker.d.ts

@@ -0,0 +1,21 @@
+import type { Attribution } from '../core/types.js';
+/**
+ * First and last campaign touch. The caller decides when storage may be used: reading or writing device storage both
+ * need analytics consent (ePrivacy Directive Art. 5(3)).
+ */
+export declare const createAttributionTracker: ({ ttlDays }: {
+    ttlDays: number;
+}) => {
+    /** Records a touch in memory. */
+    observe(touch: Attribution | undefined): void;
+    /** Merges touches stored on earlier visits: the oldest unexpired first touch wins; this session's last touch wins. */
+    restore(): void;
+    persist(): void;
+    /** Erases stored touches, e.g. when analytics consent is withdrawn. In-memory touches are kept for this page. */
+    erase(): void;
+    get: () => {
+        firstTouch: Attribution | undefined;
+        lastTouch: Attribution | undefined;
+    };
+};
+export type AttributionTracker = ReturnType<typeof createAttributionTracker>;

package/dist/chunks/core.js

@@ -1,10 +1,124 @@
-//#region lib/core/consent.ts
-var e = [
+//#region lib/core/validate.ts
+var e = /^[A-Za-z][A-Za-z0-9_]{0,39}$/, t = [
+	"google_",
+	"ga_",
+	"firebase_"
+], n = 25, r = 100, i = {
+	page_location: 1e3,
+	page_referrer: 420,
+	page_title: 300
+}, a = [
+	"email",
+	"phone",
+	"first_name",
+	"last_name",
+	"address",
+	"password"
+], o = String.raw`[\w.+-]+(?:@|%40)[\w-]+(?:\.[\w-]+)+`, s = "[redacted]", c = (n) => {
+	if (!e.test(n)) return "must start with a letter, contain only letters, digits and underscores, and be at most 40 characters";
+	let r = t.find((e) => n.toLowerCase().startsWith(e));
+	return r && `must not start with the reserved prefix "${r}"`;
+}, ee = (e) => {
+	let t = c(e);
+	return t && `event name "${e}" ${t}`;
+}, l = (e) => {
+	let t = Object.keys(e), a = t.flatMap((t) => {
+		let n = c(t);
+		if (n) return [`param "${t}" ${n}`];
+		let a = e[t], o = i[t] ?? r;
+		return typeof a == "string" && a.length > o ? [`param "${t}" is longer than ${o} characters`] : [];
+	});
+	return t.length > n ? [`has ${t.length} params; the limit is ${n}`, ...a] : a;
+}, u = (e) => new RegExp(o, "i").test(e), d = (e, t) => (typeof t == "string" || typeof t == "number") && a.some((t) => e.toLowerCase().includes(t)) ? s : typeof t == "string" ? t.replace(new RegExp(o, "gi"), s) : t, f = (e) => {
+	let t = Object.entries(e).map(([e, t]) => [
+		e,
+		t,
+		d(e, t)
+	]);
+	return {
+		params: Object.fromEntries(t.map(([e, , t]) => [e, t])),
+		redactedKeys: t.filter(([, e, t]) => t !== e).map(([e]) => e)
+	};
+}, p = [
+	"utm_source",
+	"utm_medium",
+	"utm_campaign",
+	"utm_term",
+	"utm_content",
+	"utm_id",
+	"utm_source_platform",
+	"utm_creative_format",
+	"utm_marketing_tactic",
+	"gclid",
+	"gbraid",
+	"wbraid",
+	"dclid",
+	"fbclid",
+	"msclkid",
+	"ttclid",
+	"li_fat_id",
+	"twclid"
+], m = 100, h = (e) => {
+	if (!URL.canParse(e)) return;
+	let { origin: t, pathname: n } = new URL(e);
+	return t + n;
+}, g = ({ url: e, referrer: t, capturedAt: n }) => {
+	if (!URL.canParse(e)) return;
+	let { searchParams: r } = new URL(e), i = p.flatMap((e) => {
+		let t = r.get(e)?.trim();
+		return t ? [[e, t]] : [];
+	});
+	if (i.length === 0) return;
+	let { params: a } = f(Object.fromEntries(i)), o = Object.fromEntries(Object.entries(a).map(([e, t]) => [e, String(t).slice(0, m)])), s = t ? h(t) : void 0;
+	return {
+		...o,
+		landing_page: h(e) ?? e,
+		...s ? { referrer: s } : {},
+		captured_at: n
+	};
+}, _ = (e) => typeof e == "object" && !!e, v = (e) => {
+	if (_(e) && typeof e.captured_at == "number" && typeof e.landing_page == "string") return {
+		...Object.fromEntries(p.flatMap((t) => typeof e[t] == "string" ? [[t, e[t]]] : [])),
+		landing_page: e.landing_page,
+		...typeof e.referrer == "string" ? { referrer: e.referrer } : {},
+		captured_at: e.captured_at
+	};
+}, te = ({ fbcCookie: e, touch: t }) => e ?? (t?.fbclid ? `fb.1.${t.captured_at}.${t.fbclid}` : void 0), y = "rmt:attribution:first", b = "rmt:attribution:last", x = 864e5, S = (e, t) => {
+	try {
+		return t(window[e]);
+	} catch {
+		return;
+	}
+}, C = (e, t) => S(e, (e) => {
+	let n = e.getItem(t);
+	return n === null ? void 0 : v(JSON.parse(n));
+}), ne = ({ ttlDays: e }) => {
+	let t, n, r = (t) => Date.now() - t.captured_at < e * x;
+	return {
+		observe(e) {
+			e && (t ??= e, n = e);
+		},
+		restore() {
+			let e = C("localStorage", y);
+			e && r(e) && (!t || e.captured_at <= t.captured_at) && (t = e), n ??= C("sessionStorage", b);
+		},
+		persist() {
+			S("localStorage", (e) => t && r(t) ? e.setItem(y, JSON.stringify(t)) : e.removeItem(y)), n && S("sessionStorage", (e) => e.setItem(b, JSON.stringify(n)));
+		},
+		erase() {
+			S("localStorage", (e) => e.removeItem(y)), S("sessionStorage", (e) => e.removeItem(b));
+		},
+		get: () => ({
+			firstTouch: t,
+			lastTouch: n
+		})
+	};
+}, w = [
 	"analytics",
 	"ads",
 	"adUserData",
 	"adPersonalization"
-], t = (e) => e === "granted" || e === "denied", n = ({ consent: e, gpc: t }) => {
+], T = (e) => e === "granted" || e === "denied", E = ({ consent: e, gpc: t }) => {
 	let n = t ? "denied" : e;
 	return {
 		analytics: e,
@@ -12,35 +126,35 @@ var e = [
 		adUserData: n,
 		adPersonalization: n
 	};
-}, r = (e, t) => ({
+}, D = (e, t) => ({
 	analytics: t.analytics ?? e.analytics,
 	ads: t.ads ?? e.ads,
 	adUserData: t.adUserData ?? t.ads ?? e.adUserData,
 	adPersonalization: t.adPersonalization ?? t.ads ?? e.adPersonalization
-}), i = (e) => ({
+}), O = (e) => ({
 	analytics_storage: e.analytics,
 	ad_storage: e.ads,
 	ad_user_data: e.adUserData,
 	ad_personalization: e.adPersonalization
-}), a = (e) => Object.values(e).includes("denied"), o = () => typeof navigator < "u" && navigator.globalPrivacyControl === !0, s = () => window.dataLayer ??= [], c = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/gtag/js")), l = () => window.gtag ??= function() {
-	s().push(arguments);
-}, u = ({ consent: e, waitForUpdate: t }) => {
-	l()("consent", "default", {
-		...i(e),
-		...a(e) ? { wait_for_update: t } : {}
+}), k = (e) => Object.values(e).includes("denied"), re = () => typeof navigator < "u" && navigator.globalPrivacyControl === !0, A = () => window.dataLayer ??= [], ie = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/gtag/js")), j = () => window.gtag ??= function() {
+	A().push(arguments);
+}, M = ({ consent: e, waitForUpdate: t }) => {
+	j()("consent", "default", {
+		...O(e),
+		...k(e) ? { wait_for_update: t } : {}
 	});
-}, d = (e) => {
-	l()("consent", "update", i(e));
-}, f = (e, t) => {
+}, N = (e) => {
+	j()("consent", "update", O(e));
+}, P = (e, t) => {
 	let n = URL.canParse(e) ? new URL(e) : void 0;
 	if (n?.protocol !== "https:") throw Error(`[react-marketing-tools] ${t} must be an https:// URL (received ${JSON.stringify(e)}).`);
 	return n;
-}, p = (e) => Array.from(document.scripts).some((t) => t.src === e), m = ({ src: e, nonce: t }) => {
+}, F = (e) => Array.from(document.scripts).some((t) => t.src === e), I = ({ src: e, nonce: t }) => {
 	let n = document.createElement("script");
 	n.async = !0, n.src = e, t && n.setAttribute("nonce", t), document.head.append(n);
-}, h = /^G-[A-Z0-9]+$/, g = ({ measurementId: e, pageViews: t = "auto", loadScript: n = !0, serverContainerUrl: r, waitForUpdate: i = 500, nonce: a }) => {
-	if (!h.test(e)) throw Error(`[react-marketing-tools] ga4.measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)}).`);
-	r !== void 0 && f(r, "ga4.serverContainerUrl");
+}, L = /^G-[A-Z0-9]+$/, R = ({ measurementId: e, pageViews: t = "auto", loadScript: n = !0, serverContainerUrl: r, waitForUpdate: i = 500, nonce: a }) => {
+	if (!L.test(e)) throw Error(`[react-marketing-tools] ga4.measurementId must look like "G-XXXXXXX" (received ${JSON.stringify(e)}).`);
+	r !== void 0 && P(r, "ga4.serverContainerUrl");
 	let o = `https://www.googletagmanager.com/gtag/js?id=${e}`, s = (e, t) => r ? {
 		...e,
 		event_id: t
@@ -48,77 +162,78 @@ var e = [
 	return {
 		name: "ga4",
 		start({ consent: s }) {
-			u({
+			M({
 				consent: s,
 				waitForUpdate: i
-			}), c() || (l()("js", /* @__PURE__ */ new Date()), n && m({
+			}), ie() || (j()("js", /* @__PURE__ */ new Date()), n && I({
 				src: o,
 				nonce: a
-			})), l()("config", e, {
+			})), j()("config", e, {
 				...t === "manual" ? { send_page_view: !1 } : {},
 				...r ? { server_container_url: r } : {}
 			});
 		},
 		track({ name: e, params: t, eventId: n }) {
-			l()("event", e, s(t, n));
+			j()("event", e, s(t, n));
 		},
 		consent(e) {
-			d(e);
+			N(e);
 		},
 		page({ params: e, eventId: n }) {
-			t === "manual" && l()("event", "page_view", s(e, n));
+			t === "manual" && j()("event", "page_view", s(e, n));
 		},
 		identify({ userId: e }) {
-			l()("set", { user_id: e });
+			j()("set", { user_id: e });
 		},
 		reset() {
-			l()("set", { user_id: null });
+			j()("set", { user_id: null });
 		}
 	};
-}, _ = /^GTM-[A-Z0-9]+$/, v = (e, t) => {
-	let n = f(t ?? "https://www.googletagmanager.com/gtm.js", "gtm.scriptUrl");
+}, z = /^GTM-[A-Z0-9]+$/, B = (e, t) => {
+	let n = P(t ?? "https://www.googletagmanager.com/gtm.js", "gtm.scriptUrl");
 	return n.searchParams.set("id", e), n.href;
-}, y = ({ containerId: e, loadScript: t = !0, scriptUrl: n, waitForUpdate: r = 500, nonce: i }) => {
-	if (!_.test(e)) throw Error(`[react-marketing-tools] gtm.containerId must look like "GTM-XXXXXXX" (received ${JSON.stringify(e)}).`);
-	let a = v(e, n);
+}, V = ({ containerId: e, loadScript: t = !0, scriptUrl: n, waitForUpdate: r = 500, nonce: i }) => {
+	if (!z.test(e)) throw Error(`[react-marketing-tools] gtm.containerId must look like "GTM-XXXXXXX" (received ${JSON.stringify(e)}).`);
+	let a = B(e, n);
 	return {
 		name: "gtm",
 		start({ consent: e }) {
-			u({
+			M({
 				consent: e,
 				waitForUpdate: r
-			}), t && !p(a) && (s().push({
+			}), t && !F(a) && (A().push({
 				"gtm.start": Date.now(),
 				event: "gtm.js"
-			}), m({
+			}), I({
 				src: a,
 				nonce: i
 			}));
 		},
-		track({ name: e, params: t, eventId: n }) {
-			s().push({
+		track({ name: e, params: t, eventId: n, attribution: r }) {
+			A().push({
 				...t,
+				...r && { attribution: r },
 				event: e,
 				event_id: n
 			});
 		},
 		consent(e) {
-			d(e);
+			N(e);
 		},
 		identify({ userId: e }) {
-			s().push({
+			A().push({
 				event: "identify",
 				user_id: e
 			});
 		},
 		reset() {
-			s().push({
+			A().push({
 				event: "reset",
 				user_id: void 0
 			});
 		}
 	};
-}, b = /* @__PURE__ */ new Set([
+}, H = /* @__PURE__ */ new Set([
 	"AddPaymentInfo",
 	"AddToCart",
 	"AddToWishlist",
@@ -137,7 +252,7 @@ var e = [
 	"SubmitApplication",
 	"Subscribe",
 	"ViewContent"
-]), x = {
+]), U = {
 	purchase: "Purchase",
 	sign_up: "CompleteRegistration",
 	generate_lead: "Lead",
@@ -147,8 +262,8 @@ var e = [
 	search: "Search",
 	add_payment_info: "AddPaymentInfo",
 	add_to_wishlist: "AddToWishlist"
-}, S = (e) => typeof e == "object" && !!e, C = (e) => {
-	let t = e.filter(S).filter((e) => e.item_id !== void 0).map((e) => ({
+}, W = (e) => typeof e == "object" && !!e, G = (e) => {
+	let t = e.filter(W).filter((e) => e.item_id !== void 0).map((e) => ({
 		id: String(e.item_id),
 		quantity: typeof e.quantity == "number" ? e.quantity : 1
 	}));
@@ -158,21 +273,21 @@ var e = [
 		num_items: t.reduce((e, t) => e + t.quantity, 0),
 		content_type: "product"
 	};
-}, w = ({ items: e, search_term: t, ...n }) => ({
+}, K = ({ items: e, search_term: t, ...n }) => ({
 	...n,
 	...typeof t == "string" ? { search_string: t } : {},
-	...Array.isArray(e) ? C(e) : {}
-}), T = ({ name: e, params: t, options: n }) => {
-	let r = n?.meta, i = r?.event ?? x[e] ?? e;
+	...Array.isArray(e) ? G(e) : {}
+}), q = ({ name: e, params: t, options: n }) => {
+	let r = n?.meta, i = r?.event ?? U[e] ?? e;
 	return {
-		command: b.has(i) ? "track" : "trackCustom",
+		command: H.has(i) ? "track" : "trackCustom",
 		name: i,
 		params: {
-			...w(t),
+			...K(t),
 			...r?.params
 		}
 	};
-}, E = /^\d+$/, D = "https://connect.facebook.net/en_US/fbevents.js", O = () => {
+}, J = /^\d+$/, ae = "https://connect.facebook.net/en_US/fbevents.js", Y = () => {
 	let e = window;
 	if (!e.fbq) {
 		let t = function() {
@@ -182,122 +297,96 @@ var e = [
 		t.push = t, t.loaded = !0, t.version = "2.0", t.queue = [], e.fbq = t, e._fbq ??= t;
 	}
 	return e.fbq;
-}, k = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/fbevents.js")), A = ({ userId: e, traits: t }) => Object.fromEntries(Object.entries({
+}, oe = () => Array.from(document.scripts).some((e) => URL.canParse(e.src) && new URL(e.src).pathname.endsWith("/fbevents.js")), se = ({ userId: e, traits: t }) => Object.fromEntries(Object.entries({
 	external_id: e,
 	em: t.email,
 	ph: t.phone,
 	fn: t.firstName,
 	ln: t.lastName
-}).filter(([, e]) => e !== void 0)), j = (e) => e.adUserData === "granted" ? "grant" : "revoke", M = ({ pixelId: e, pageViews: t = "auto", loadScript: n = !0, nonce: r }) => {
-	if (!E.test(e)) throw Error(`[react-marketing-tools] metaPixel.pixelId must be the numeric pixel ID (received ${JSON.stringify(e)}).`);
+}).filter(([, e]) => e !== void 0)), X = (e) => e.adUserData === "granted" ? "grant" : "revoke", ce = ({ pixelId: e, pageViews: t = "auto", loadScript: n = !0, nonce: r }) => {
+	if (!J.test(e)) throw Error(`[react-marketing-tools] metaPixel.pixelId must be the numeric pixel ID (received ${JSON.stringify(e)}).`);
 	return {
 		name: "metaPixel",
 		start({ consent: i, identity: a }) {
-			let o = O();
-			t === "manual" && (o.disablePushState = !0), j(i) === "revoke" && o("consent", "revoke"), a ? o("init", e, A(a)) : o("init", e), t === "auto" && o("track", "PageView"), n && !k() && m({
-				src: D,
+			let o = Y();
+			t === "manual" && (o.disablePushState = !0), X(i) === "revoke" && o("consent", "revoke"), a ? o("init", e, se(a)) : o("init", e), t === "auto" && o("track", "PageView"), n && !oe() && I({
+				src: ae,
 				nonce: r
 			});
 		},
 		track(e) {
-			let { command: t, name: n, params: r } = T(e);
-			O()(t, n, r, { eventID: e.eventId });
+			let { command: t, name: n, params: r } = q(e);
+			Y()(t, n, r, { eventID: e.eventId });
 		},
 		page({ eventId: e }) {
-			t === "manual" && O()("track", "PageView", {}, { eventID: e });
+			t === "manual" && Y()("track", "PageView", {}, { eventID: e });
 		},
 		consent(e) {
-			O()("consent", j(e));
+			Y()("consent", X(e));
 		}
 	};
-}, N = class extends Error {
+}, Z = class extends Error {
 	code;
 	constructor(e, t, n) {
 		super(`[react-marketing-tools] ${t}`, n), this.name = "AnalyticsError", this.code = e;
 	}
-}, P = /^[A-Za-z][A-Za-z0-9_]{0,39}$/, F = [
-	"google_",
-	"ga_",
-	"firebase_"
-], I = 25, L = 100, R = {
-	page_location: 1e3,
-	page_referrer: 420,
-	page_title: 300
-}, z = [
-	"email",
-	"phone",
-	"first_name",
-	"last_name",
-	"address",
-	"password"
-], B = String.raw`[\w.+-]+(?:@|%40)[\w-]+(?:\.[\w-]+)+`, V = "[redacted]", H = (e) => {
-	if (!P.test(e)) return "must start with a letter, contain only letters, digits and underscores, and be at most 40 characters";
-	let t = F.find((t) => e.toLowerCase().startsWith(t));
-	return t && `must not start with the reserved prefix "${t}"`;
-}, U = (e) => {
-	let t = H(e);
-	return t && `event name "${e}" ${t}`;
-}, W = (e) => {
-	let t = Object.keys(e), n = t.flatMap((t) => {
-		let n = H(t);
-		if (n) return [`param "${t}" ${n}`];
-		let r = e[t], i = R[t] ?? L;
-		return typeof r == "string" && r.length > i ? [`param "${t}" is longer than ${i} characters`] : [];
-	});
-	return t.length > I ? [`has ${t.length} params; the limit is ${I}`, ...n] : n;
-}, G = (e) => new RegExp(B, "i").test(e), K = (e, t) => (typeof t == "string" || typeof t == "number") && z.some((t) => e.toLowerCase().includes(t)) ? V : typeof t == "string" ? t.replace(new RegExp(B, "gi"), V) : t, q = (e) => {
-	let t = Object.entries(e).map(([e, t]) => [
-		e,
-		t,
-		K(e, t)
-	]);
-	return {
-		params: Object.fromEntries(t.map(([e, , t]) => [e, t])),
-		redactedKeys: t.filter(([, e, t]) => t !== e).map(([e]) => e)
-	};
-}, J = () => typeof window < "u", Y = () => typeof crypto.randomUUID == "function" ? crypto.randomUUID() : "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (e) => (Number(e) ^ crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(1))[0] & 15 >> Number(e) / 4).toString(16)), X = (e) => {
+}, Q = (e, t) => {
+	for (let n of e.split(";")) {
+		let e = n.indexOf("=");
+		if (e !== -1 && n.slice(0, e).trim() === t) return n.slice(e + 1).trim();
+	}
+}, $ = () => typeof window < "u", le = 90, ue = () => typeof crypto.randomUUID == "function" ? crypto.randomUUID() : "10000000-1000-4000-8000-100000000000".replace(/[018]/g, (e) => (Number(e) ^ crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(1))[0] & 15 >> Number(e) / 4).toString(16)), de = (e) => {
 	if (e.consent !== "granted" && e.consent !== "denied") throw Error(`[react-marketing-tools] createAnalytics: "consent" must be 'granted' or 'denied' (received ${JSON.stringify(e.consent)}).`);
-}, Z = (i) => {
-	X(i);
-	let { debug: a = !1, onError: s = console.error, respectGpc: c = !0 } = i, l = n({
-		consent: i.consent,
-		gpc: c && o()
-	}), u = l, d, f = [
-		...i.gtm ? [y({
-			...i.gtm,
-			nonce: i.nonce
+}, fe = (e) => {
+	de(e);
+	let { debug: t = !1, onError: n = console.error, respectGpc: r = !0 } = e, i = E({
+		consent: e.consent,
+		gpc: r && re()
+	}), a = i, o, s = [
+		...e.gtm ? [V({
+			...e.gtm,
+			nonce: e.nonce
 		})] : [],
-		...i.ga4 ? [g({
-			...i.ga4,
-			nonce: i.nonce
+		...e.ga4 ? [R({
+			...e.ga4,
+			nonce: e.nonce
 		})] : [],
-		...i.metaPixel ? [M({
-			...i.metaPixel,
-			nonce: i.nonce
+		...e.metaPixel ? [ce({
+			...e.metaPixel,
+			nonce: e.nonce
 		})] : [],
-		...i.destinations ?? []
-	], p = [], m = !1, h = (e) => {
-		if (a) throw e;
-		s(e);
-	}, _ = (e) => {
-		for (let t of f) try {
+		...e.destinations ?? []
+	], c = [], d = !1, p = e.attribution === !1 ? void 0 : ne({ ttlDays: typeof e.attribution == "object" && e.attribution.ttlDays || le }), m = !1, h = () => {
+		m || (m = !0, p?.observe(g({
+			url: location.href,
+			referrer: document.referrer,
+			capturedAt: Date.now()
+		})));
+	}, _ = () => d && a.analytics === "granted", v = (e) => {
+		if (t) throw e;
+		n(e);
+	}, y = (e) => {
+		for (let t of s) try {
 			e(t);
 		} catch (e) {
-			s(new N("destination_failed", `destination "${t.name}" failed`, { cause: e }));
+			n(new Z("destination_failed", `destination "${t.name}" failed`, { cause: e }));
 		}
-	}, v = (e) => {
-		m ? _(e) : p.push(e);
-	}, b = ({ name: e, params: t, options: n }) => {
-		let r = U(e);
+	}, b = (e) => {
+		d ? y(e) : c.push(e);
+	}, x = ({ name: e, params: t, options: n }) => {
+		let r = ee(e);
 		if (r) {
-			h(new N("invalid_event", r));
+			v(new Z("invalid_event", r));
 			return;
 		}
-		for (let n of W(t)) h(new N("invalid_param", `event "${e}" ${n}`));
-		let i = q(t), a = n?.meta?.params && q(n.meta.params), o = [...i.redactedKeys, ...a?.redactedKeys.map((e) => `meta.${e}`) ?? []];
-		return o.length > 0 && h(new N("pii_redacted", `event "${e}": personal data redacted from ${o.join(", ")}`)), {
+		for (let n of l(t)) v(new Z("invalid_param", `event "${e}" ${n}`));
+		let i = f(t), a = n?.meta?.params && f(n.meta.params), o = [...i.redactedKeys, ...a?.redactedKeys.map((e) => `meta.${e}`) ?? []];
+		o.length > 0 && v(new Z("pii_redacted", `event "${e}": personal data redacted from ${o.join(", ")}`)), h();
+		let s = p?.get().lastTouch;
+		return {
 			name: e,
 			params: i.params,
+			...s && { attribution: s },
 			...n && { options: a ? {
 				...n,
 				meta: {
@@ -305,29 +394,33 @@ var e = [
 					params: a.params
 				}
 			} : n },
-			eventId: Y(),
+			eventId: ue(),
 			timestamp: Date.now()
 		};
 	};
 	return {
 		start() {
-			!m && J() && (m = !0, _((e) => e.start({
-				consent: l,
-				identity: d
-			})), p.splice(0).forEach(_));
+			!d && $() && (d = !0, h(), _() && (p?.restore(), p?.persist()), y((e) => e.start({
+				consent: i,
+				identity: o
+			})), c.splice(0).forEach(y));
 		},
 		track(e, t = {}, n) {
-			if (!J()) return;
-			let r = b({
+			if (!$()) return;
+			let r = x({
 				name: e,
 				params: t,
 				options: n
 			});
-			r && v((e) => e.track(r));
+			r && b((e) => e.track(r));
 		},
 		page(e = {}) {
-			if (!J()) return;
-			let t = b({
+			if (!$()) return;
+			h(), p?.observe(g({
+				url: location.href,
+				capturedAt: Date.now()
+			})), _() && p?.persist();
+			let t = x({
 				name: "page_view",
 				params: {
 					page_location: location.href,
@@ -335,37 +428,52 @@ var e = [
 					...e
 				}
 			});
-			t && v((e) => e.page ? e.page(t) : e.track(t));
+			t && b((e) => e.page ? e.page(t) : e.track(t));
 		},
 		identify(e, t = {}) {
-			if (!J()) return;
-			if (!e || G(e)) {
-				h(new N("invalid_user_id", "identify() needs a non-empty user id that is not personal data such as an email address"));
+			if (!$()) return;
+			if (!e || u(e)) {
+				v(new Z("invalid_user_id", "identify() needs a non-empty user id that is not personal data such as an email address"));
 				return;
 			}
 			let n = {
 				userId: e,
 				traits: t
 			};
-			d = n, v((e) => e.identify?.(n));
+			o = n, b((e) => e.identify?.(n));
 		},
 		reset() {
-			J() && (d = void 0, v((e) => e.reset?.()));
+			$() && (o = void 0, b((e) => e.reset?.()));
 		},
 		consent: {
-			update(n) {
-				if (!J()) return;
-				let i = Object.entries(n).filter(([n, r]) => r !== void 0 && !(e.includes(n) && t(r)));
-				if (i.length > 0) {
-					h(new N("invalid_consent", `consent.update() ignored: ${i.map(([e, t]) => `${e}=${JSON.stringify(t)}`).join(", ")}. Use analytics, ads, adUserData or adPersonalization with 'granted' or 'denied'.`));
+			update(e) {
+				if (!$()) return;
+				let t = Object.entries(e).filter(([e, t]) => t !== void 0 && !(w.includes(e) && T(t)));
+				if (t.length > 0) {
+					v(new Z("invalid_consent", `consent.update() ignored: ${t.map(([e, t]) => `${e}=${JSON.stringify(t)}`).join(", ")}. Use analytics, ads, adUserData or adPersonalization with 'granted' or 'denied'.`));
 					return;
 				}
-				let a = r(u, n);
-				u = a, v((e) => e.consent?.(a));
+				let n = a, r = D(a, e);
+				a = r, n.analytics === "granted" && r.analytics === "denied" ? p?.erase() : _() && (p?.restore(), p?.persist()), b((e) => e.consent?.(r));
 			},
-			get: () => u
+			get: () => a
+		},
+		getAttribution() {
+			if (!$()) return {};
+			h();
+			let e = p?.get() ?? {};
+			if (a.adUserData !== "granted") return e;
+			let t = Q(document.cookie, "_fbp"), n = te({
+				fbcCookie: Q(document.cookie, "_fbc"),
+				touch: e.lastTouch
+			});
+			return {
+				...e,
+				...n && { fbc: n },
+				...t && { fbp: t }
+			};
 		}
 	};
 };
 //#endregion
-export { N as n, Z as t };
+export { Z as n, fe as t };

package/dist/core/types.d.ts

@@ -21,10 +21,32 @@ export type TrackOptions = {
         params?: EventParams;
     };
 };
+export type CampaignParam = 'utm_source' | 'utm_medium' | 'utm_campaign' | 'utm_term' | 'utm_content' | 'utm_id' | 'utm_source_platform' | 'utm_creative_format' | 'utm_marketing_tactic' | 'gclid' | 'gbraid' | 'wbraid' | 'dclid' | 'fbclid' | 'msclkid' | 'ttclid' | 'li_fat_id' | 'twclid';
+/** Where a visit came from: the campaign params and ad click IDs of its landing URL. */
+export type Attribution = Partial<Record<CampaignParam, string>> & {
+    /** Origin and path of the landing page, without its query string. */
+    landing_page: string;
+    /** Origin and path of the referring page, when there was one. */
+    referrer?: string;
+    /** Milliseconds since the Unix epoch when the visit was captured. */
+    captured_at: number;
+};
+export type AttributionSnapshot = {
+    /** The first campaign touch within the attribution window. */
+    firstTouch?: Attribution;
+    /** The most recent campaign touch in this browser session. */
+    lastTouch?: Attribution;
+    /** Meta click ID (`_fbc`), for the Conversions API. Only with `adUserData` consent. */
+    fbc?: string;
+    /** Meta browser ID (`_fbp`), for the Conversions API. Only with `adUserData` consent. */
+    fbp?: string;
+};
 export type AnalyticsEvent = {
     name: string;
     params: EventParams;
     options?: TrackOptions;
+    /** The last campaign touch when the event was tracked. */
+    attribution?: Attribution;
     /** Unique per `track()` call and shared by every destination, so vendors can deduplicate the same event. */
     eventId: string;
     /** Milliseconds since the Unix epoch at the moment `track()` was called. */
@@ -108,6 +130,13 @@ export type AnalyticsConfig = {
      * An explicit `analytics.consent.update()` still wins.
      */
     respectGpc?: boolean;
+    /**
+     * Capture UTM params and ad click IDs from landing URLs. Defaults to `true`. First and last touch are stored in the
+     * browser only with analytics consent; `ttlDays` (default 90) is how long a first touch is kept.
+     */
+    attribution?: boolean | {
+        ttlDays?: number;
+    };
     gtm?: GtmConfig;
     ga4?: Ga4Config;
     metaPixel?: MetaPixelConfig;
@@ -131,6 +160,8 @@ export type Analytics = {
     identify(userId: string, traits?: IdentityTraits): void;
     /** Forgets the identified user, e.g. on logout. */
     reset(): void;
+    /** Campaign attribution for this visitor. Empty outside the browser. */
+    getAttribution(): AttributionSnapshot;
     consent: {
         /** Records the visitor's choice, e.g. from your consent banner. Omitted purposes keep their current state. */
         update(update: ConsentUpdate): void;

package/dist/core.d.ts

@@ -1,4 +1,4 @@
 export { createAnalytics } from './core/createAnalytics.js';
 export { AnalyticsError } from './core/errors.js';
 export type { AnalyticsErrorCode } from './core/errors.js';
-export type { Analytics, AnalyticsConfig, AnalyticsEvent, ConsentState, ConsentStatus, ConsentUpdate, Destination, EventParams, Ga4Config, GtmConfig, Identity, IdentityTraits, MetaPixelConfig, TrackOptions, } from './core/types.js';
+export type { Analytics, AnalyticsConfig, AnalyticsEvent, Attribution, AttributionSnapshot, CampaignParam, ConsentState, ConsentStatus, ConsentUpdate, Destination, EventParams, Ga4Config, GtmConfig, Identity, IdentityTraits, MetaPixelConfig, TrackOptions, } from './core/types.js';

package/dist/shared/cookies.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Reads one cookie from a `document.cookie` string or an HTTP `Cookie` header. Values are returned as stored; an
+ * `=` inside a value is kept.
+ */
+export declare const parseCookie: (cookies: string, name: string) => string | undefined;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "react-marketing-tools",
   "type": "module",
-  "version": "1.0.0-alpha.4",
-  "description": "React Marketing Tools are a set of tools to make it easier for you to implement analytics and track user journeys, interactions throughout your App. using dataLayer/Google Tag Manager, GA4 fetch directly or coming soon facebook pixel.",
+  "version": "1.0.0-alpha.5",
+  "description": "One track() call for Google Tag Manager, Google Analytics 4 and the Meta Pixel, with Consent Mode v2, UTM attribution and personal-data redaction built in. React bindings included.",
   "license": "MIT",
   "author": "bronz3beard <exempli.gratia.webdesign@gmail.com> (https://www.heyrory.com/)",
   "homepage": "https://www.heyrory.com/",
@@ -17,17 +17,22 @@
     "dist"
   ],
   "keywords": [
-    "javascript",
     "react",
-    "marketing",
-    "tools",
-    "marketing tools",
     "analytics",
-    "google",
-    "facebook",
-    "GA4",
-    "pixel",
-    "dataLayer"
+    "marketing",
+    "google-tag-manager",
+    "gtm",
+    "datalayer",
+    "google-analytics",
+    "ga4",
+    "gtag",
+    "meta-pixel",
+    "facebook-pixel",
+    "consent-mode",
+    "gdpr",
+    "utm",
+    "attribution",
+    "server-side-tagging"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",