@tagadapay/headless-sdk 1.14.0 → 1.16.0

package/dist/pixels/pixelTracker.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Framework-agnostic pixel tracker.
+ *
+ * Init / fire logic for Meta, TikTok, Snapchat, Pinterest, GTM/GA4 and
+ * Microsoft Clarity pixels —
+ * extracted from `react/hooks/usePixelTracking.tsx` so non-React entry points
+ * (Studio islands hydrator, full-SPA runtime) can fire pixel events from
+ * `window.__TGD_STEP_CONFIG__.pixels`.
+ *
+ * The React provider is a thin adapter on top of this module.
+ */
+import type { PixelsConfig } from './types.js';
+import { type Ga4UserData, type StandardPixelEvent } from './pixelMapping.js';
+import { type PixelRawIdentity } from './pixelIdentity.js';
+/**
+ * Optional per-event tracking metadata. `eventId` is the cross-channel dedup
+ * key that the SDK threads to `fbq` (Meta) and `ttq` (TikTok) so the same
+ * eventID/event_id can be matched against a server-side CAPI event. Use the
+ * `makeMetaEventId(eventName, entityId)` helper from `core/utils/metaEventId`
+ * to keep the formula in lockstep with the server.
+ */
+export interface TrackOptions {
+    eventId?: string;
+}
+export interface PixelTracker {
+    /** Resolves once all pixel scripts have loaded (or hit their load timeout). */
+    readonly initPromise: Promise<void>;
+    /** True after `initPromise` resolves. */
+    readonly pixelsInitialized: boolean;
+    /** Track a standard pixel event. No-ops until init resolves. */
+    track(eventName: StandardPixelEvent, parameters?: Record<string, unknown>, options?: TrackOptions): void;
+    /**
+     * Feed customer identifiers for advanced matching. Applies to Meta (fbq init,
+     * raw — Meta hashes in-browser), Google (gtag set user_data, raw — enhanced
+     * conversions), Snapchat (re-init) + TikTok (identify), the last two with
+     * client-side SHA-256 hashing. Each provider persists the keys onto
+     * subsequent events, so call this as soon as the email is known to lift
+     * match quality on InitiateCheckout + Purchase. Idempotent per identity; safe
+     * to call repeatedly.
+     */
+    identify(identity: PixelRawIdentity): void;
+}
+/**
+ * Google Ads enhanced conversions / GA4 user-provided data.
+ *
+ * Google's documented mechanism is `gtag('set', 'user_data', {...})` BEFORE the
+ * conversion event fires (support.google.com/google-ads/answer/13258081) —
+ * `user_data` as an event parameter is not read for enhanced conversions. We
+ * pass RAW values; the Google tag normalizes + SHA-256 hashes in-browser.
+ * Field names per spec: `email`, `phone_number` (strict E.164 — dropped when
+ * not in that shape, email is the preferred key anyway), and
+ * `address.{first_name,last_name,street,city,region,postal_code,country}`.
+ * Exported for unit tests.
+ */
+export declare function applyGoogleIdentity(w: any, ud: Ga4UserData): void;
+/** True when `value` is a single, well-formed pixel / container ID. */
+export declare function isSafePixelId(value: unknown): value is string;
+/**
+ * Create a pixel tracker for a given pixels config.
+ * Kicks off pixel script init once the first frame has painted, fires PageView
+ * when init resolves, and returns a `track()` function that no-ops until then.
+ */
+export declare function createPixelTracker(rawPixels: PixelsConfig | undefined, opts?: {
+    autoPageView?: boolean;
+}): PixelTracker;
+declare global {
+    interface Window {
+        __TGD_PIXEL_TRACKER__?: PixelTracker;
+        __TGD_STEP_CONFIG__?: string | Record<string, unknown>;
+    }
+}
+/**
+ * One-shot bootstrap: reads `window.__TGD_STEP_CONFIG__.pixels`, creates a
+ * tracker, kicks off init, and stashes it on `window.__TGD_PIXEL_TRACKER__`.
+ *
+ * Idempotent — both the islands SDK and the full-SPA runtime may call this,
+ * but only the first call creates a tracker. Returns the active tracker
+ * (existing or newly created), or null if there's no window or no pixels.
+ */
+export declare function bootstrapPixelTrackerFromWindow(): PixelTracker | null;
+//# sourceMappingURL=pixelTracker.d.ts.map

package/dist/pixels/pixelTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pixelTracker.d.ts","sourceRoot":"","sources":["../../src/pixels/pixelTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAyD,YAAY,EAAE,MAAM,YAAY,CAAC;AACtG,OAAO,EAKL,KAAK,WAAW,EAEhB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,oBAAoB,CAAC;AAM5B;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;IACpC,gEAAgE;IAChE,KAAK,CACH,SAAS,EAAE,kBAAkB,EAC7B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpC,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAAC;IACR;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC5C;AAmJD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,WAAW,QA0B1D;AAySD,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAE7D;AA8ED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,YAAY,GAAG,SAAS,EAAE,IAAI,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,YAAY,CAmKvH;AAMD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,qBAAqB,CAAC,EAAE,YAAY,CAAC;QACrC,mBAAmB,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxD;CACF;AAeD;;;;;;;GAOG;AACH,wBAAgB,+BAA+B,IAAI,YAAY,GAAG,IAAI,CAUrE"}