react-marketing-tools 1.0.0-alpha.4 → 1.0.0-beta.3

package/README.md

@@ -1,226 +1,161 @@
+# 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.
+
+**[Try it in the playground](https://bronz3beard.github.io/react-marketing-tools/)**: see what each vendor receives for
+every event, without sending anything.
+
+> **1.0 is in beta** on the `next` tag. `npm install react-marketing-tools` still installs 0.4.x, whose API 1.0
+> replaces; see the [migration guide](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/migration-v1.md)
+> and 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' },
+})
 ```
 
-## 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 (
-            ...
-        )
-    }
+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>,
+)
+```
+
+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>
+}
+```
+
+Or without code, with `autocapture: { clicks: true }` in the config:
+
+```html
+<button data-analytics-event="cta_click" data-analytics-param-location="hero">Start</button>
+```
+
+Follow a multi-step flow as a funnel:
+
+```ts
+const checkout = analytics.journey('checkout')
+checkout.step('shipping') // journey_start, then journey_step
+checkout.complete({ value: 42, currency: 'USD' }) // journey_complete
+```
+
+Report Core Web Vitals (LCP, INP, CLS) to GA4 and Tag Manager, after `npm install web-vitals@^6`:
+
+```ts
+import { trackWebVitals } from 'react-marketing-tools/web-vitals'
+
+void trackWebVitals(analytics)
+```
+
+The same instance identifies users, records consent and gives a consenting visitor a stable ID:
+
+```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
+const visitorId = await analytics.getVisitorId() // random by default, or a fingerprint; never sent to GA4
+```
+
+Configure only the destinations you use. Without React, import `createAnalytics` from `react-marketing-tools/core` and
+call `analytics.start()` yourself.
+
+Send events that happen on your server, such as a purchase confirmed by a payment webhook, from
+`react-marketing-tools/server`:
+
+```ts
+import { sendMeasurementProtocolEvent } from 'react-marketing-tools/server'
+
+await sendMeasurementProtocolEvent({
+  measurementId: 'G-XXXXXXX',
+  apiSecret: process.env.GA4_API_SECRET!,
+  clientId: order.ga4ClientId, // saved at checkout with readGa4Cookies()
+  events: [{ name: 'purchase', params: { transaction_id: order.id, value: 42, currency: 'USD' } }],
+})
+```
+
+`sendConversionsApiEvent` does the same for Meta, hashing customer information as Meta requires. To have Meta receive
+the events the browser Pixel misses, counted once, relay them through your server:
+
+```ts
+// analytics.ts
+createAnalytics({ /* …as above */ server: { endpoint: '/api/track' } })
+
+// app/api/track/route.ts (Next.js; any Request → Response server works)
+import { createTrackHandler } from 'react-marketing-tools/server'
 
+export const POST = createTrackHandler({
+  allowedOrigins: ['https://shop.example.com'],
+  meta: { pixelId: '1234567890123456', accessToken: process.env.META_CAPI_TOKEN! },
+})
 ```
 
-## Usage without Provider
-> To view implementation and usage without the React Context/Provider visit this [codepen](https://codepen.io/roryfn/pen/OJBGvMG)
+## What each destination receives
+
+| | Google Tag Manager | Google Analytics 4 | Meta Pixel | Conversions API relay |
+| --- | --- | --- | --- | --- |
+| `track()` | dataLayer push with `event_id` | gtag.js event | standard or custom event with `eventID` | the same event from your server |
+| `identify()` | `user_id` | `user_id` | advanced matching | user data, hashed on your server |
+| `consent.update()` | Consent Mode v2 | Consent Mode v2 | `grant` / `revoke` | only with `adUserData` |
+| Attribution | `attribution` (last touch) | read from the page URL | `fbc` | `fbc`, `fbp` |
+
+## Documentation
+
+- [All docs](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/README.md)
+- [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, journeys, click autocapture, Web Vitals, 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
+- [Visitor ID](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/visitor-id.md): a stable ID for consenting visitors, random or fingerprint
+- [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)
+- [GA4 Measurement Protocol](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/measurement-protocol.md): GA4 events from your server
+- [Meta Conversions API](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/meta-conversions-api.md): Meta events from your server
+- [Debugging](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/debugging.md): see what's sent, and fix common problems
+- [Migrating from 0.4](https://github.com/bronz3beard/react-marketing-tools/blob/main/docs/migration-v1.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/autocapture/clicks.d.ts

@@ -0,0 +1,11 @@
+import type { EventParams } from '../core/types.js';
+/**
+ * The event a click asks for: the nearest element around the click target with `data-analytics-event`, and its
+ * `data-analytics-param-*` attributes as params (`data-analytics-param-button-text` → `button_text`).
+ */
+export declare const readClickEvent: (target: EventTarget | null) => {
+    name: string;
+    params: EventParams;
+} | undefined;
+/** Tracks clicks on marked elements through one listener on the document, so elements added later are covered too. */
+export declare const captureClicks: (track: (name: string, params: EventParams) => void) => void;

package/dist/chunks/cookies.js

@@ -0,0 +1,49 @@
+//#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}"`;
+}, l = (e) => {
+	let t = c(e);
+	return t && `event name "${e}" ${t}`;
+}, u = (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;
+}, d = (e) => new RegExp(o, "i").test(e), f = (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, p = (e) => {
+	let t = Object.entries(e).map(([e, t]) => [
+		e,
+		t,
+		f(e, t)
+	]);
+	return {
+		params: Object.fromEntries(t.map(([e, , t]) => [e, t])),
+		redactedKeys: t.filter(([, e, t]) => t !== e).map(([e]) => e)
+	};
+}, m = (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();
+	}
+};
+//#endregion
+export { p as a, u as i, d as n, l as r, m as t };