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

package/README.md

@@ -6,8 +6,12 @@
 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).
+**[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
 
@@ -60,28 +64,96 @@ export const SignUpButton = () => {
 }
 ```
 
-The same instance identifies users and records consent:
+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! },
+})
+```
+
+## 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, users, personal data, errors
+- [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

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 };