@heyplaybook/hydrogen 0.2.1 → 0.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +338 -8
- package/dist/index.d.ts +786 -64
- package/dist/index.js +1935 -354
- package/package.json +2 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,139 @@
|
|
|
1
1
|
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
2
|
-
import
|
|
2
|
+
import * as react from 'react';
|
|
3
|
+
import { ReactNode, Component } from 'react';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Analytics consent — vendored from the Playbook platform's shared consent module (the
|
|
7
|
+
* storefront SDKs' single source; see Playbook's
|
|
8
|
+
* `.ai/docs/STOREFRONT-CONSENT-GATING.md`, which is binding). Keep the logic
|
|
9
|
+
* identical; this copy exists only because the store can't import the
|
|
10
|
+
* Playbook monorepo.
|
|
11
|
+
*
|
|
12
|
+
* Contract:
|
|
13
|
+
* - Read Shopify's Customer Privacy API (`analytics` purpose only, matching
|
|
14
|
+
* the checkout Web Pixel). Never integrate with a CMP directly — any CMP that
|
|
15
|
+
* feeds the API (e.g. TrueVault Polaris) works with no code here.
|
|
16
|
+
* - RENDERING is functional and never gated. The persistent visitor cookie,
|
|
17
|
+
* exposures, events and the cart attribute are ANALYTICS and are gated.
|
|
18
|
+
* - FAIL OPEN only when the API is genuinely absent; CLOSED when it exists and
|
|
19
|
+
* denies, or while a known-present API is still resolving.
|
|
20
|
+
*
|
|
21
|
+
* Client: `window`/`document` touched at CALL time only (safe to import on the
|
|
22
|
+
* server). Server: `analyticsConsentFromCookie` reads Shopify's own
|
|
23
|
+
* `_tracking_consent` cookie, the same signal the checkout pixel trusts.
|
|
24
|
+
*
|
|
25
|
+
* 0.5.0: a present API whose `consentStatus` is a string other than
|
|
26
|
+
* `'loaded'` is still resolving (pending). Before it loads, the API answers
|
|
27
|
+
* with a no-data fallback (every `*Allowed()` true, no banner owed) that
|
|
28
|
+
* would otherwise read as granted in a region that requires a banner. An
|
|
29
|
+
* API with no `consentStatus` field at all (older script versions) is read
|
|
30
|
+
* as before. The decision carried by `visitorConsentCollected`'s
|
|
31
|
+
* `event.detail` is remembered and used until the API itself has loaded.
|
|
32
|
+
*/
|
|
33
|
+
type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
|
|
34
|
+
/**
|
|
35
|
+
* Force the "a CMP is present" branch: a headless store whose CMP injects
|
|
36
|
+
* `Shopify.customerPrivacy` after we boot (e.g. TrueVault Polaris). Without it a
|
|
37
|
+
* first-time visitor with no `_tracking_consent` cookie would fail open.
|
|
38
|
+
*/
|
|
39
|
+
declare function declareConsentRequired(): void;
|
|
40
|
+
/** Wait for the API: already loaded → `loadFeatures()` → bounded poll → give up. */
|
|
41
|
+
declare function waitForConsentAPI(): Promise<void>;
|
|
42
|
+
/** Granted right now? Closed while resolving a known-present API; open if absent. */
|
|
43
|
+
declare function isAnalyticsConsentGranted(): boolean;
|
|
44
|
+
declare function getConsentState(): ConsentState;
|
|
45
|
+
/**
|
|
46
|
+
* Events after which a present API may have finished loading the visitor's
|
|
47
|
+
* consent (`consentStatus` → 'loaded'): Shopify's consent data loaded, or
|
|
48
|
+
* Hydrogen loaded the Customer Privacy script. `visitorConsentCollected` is
|
|
49
|
+
* handled by `onConsentChange` (decision read from `event.detail`).
|
|
50
|
+
*/
|
|
51
|
+
declare const CONSENT_LOADED_EVENTS: readonly ["consentTrackingApiLoaded", "shopifyCustomerPrivacyApiLoaded"];
|
|
52
|
+
/** Call `cb` after each "consent loaded" event (document and window). */
|
|
53
|
+
declare function onConsentLoaded(cb: () => void): () => void;
|
|
54
|
+
/** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
|
|
55
|
+
declare function onConsentChange(cb: (granted: boolean) => void): () => void;
|
|
56
|
+
/**
|
|
57
|
+
* SERVER: analytics consent from Shopify's `_tracking_consent` cookie.
|
|
58
|
+
* Returns `granted` / `denied`, `pending` when the cookie exists but analytics
|
|
59
|
+
* is undecided, and `absent` when there is no cookie at all. Tolerates both
|
|
60
|
+
* known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
|
|
61
|
+
* anything unparseable is `pending` (closed), never granted.
|
|
62
|
+
*/
|
|
63
|
+
declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
|
|
64
|
+
|
|
65
|
+
/** SERVER half: the decision for one request. */
|
|
66
|
+
interface PlaybookServerConsent {
|
|
67
|
+
/** Stable name, for debug output. */
|
|
68
|
+
readonly id: string;
|
|
69
|
+
/** SERVER: the decision for this request. Never throws. */
|
|
70
|
+
fromRequest(request: Request): ConsentState;
|
|
71
|
+
}
|
|
72
|
+
/** CLIENT half: the live decision in the browser. */
|
|
73
|
+
interface PlaybookClientConsent {
|
|
74
|
+
/** Stable name, for debug output. */
|
|
75
|
+
readonly id: string;
|
|
76
|
+
/** CLIENT: the decision right now. `window`/`document` read at call time. */
|
|
77
|
+
read(): ConsentState;
|
|
78
|
+
/** CLIENT: call `onChange` whenever the decision may have changed. */
|
|
79
|
+
subscribe(onChange: () => void): () => void;
|
|
80
|
+
}
|
|
81
|
+
/** Both halves from one decision function (unchanged since 0.3.0). */
|
|
82
|
+
interface PlaybookConsentAdapter extends PlaybookServerConsent, PlaybookClientConsent {
|
|
83
|
+
}
|
|
84
|
+
/**
|
|
85
|
+
* Map a store's own analytics answer to a `ConsentState`, so a store adapter
|
|
86
|
+
* doesn't hand-roll tri-state logic:
|
|
87
|
+
* `true` / `'granted'` / `'yes'` → granted, `false` / `'denied'` / `'no'` →
|
|
88
|
+
* denied, anything else (null, undefined, `'unknown'`, `''`) → pending
|
|
89
|
+
* (closed). Never `absent`: a store that wires an adapter has a consent
|
|
90
|
+
* system, so "no answer" must not fail open.
|
|
91
|
+
*/
|
|
92
|
+
declare function consentFromAnalytics(value: boolean | string | null | undefined): ConsentState;
|
|
93
|
+
/**
|
|
94
|
+
* The built-in browser source: Shopify's Customer Privacy API (what
|
|
95
|
+
* `<PlaybookRoot>` uses when no client consent is passed).
|
|
96
|
+
*
|
|
97
|
+
* - Pending while the API is resolving, and while it reports a
|
|
98
|
+
* `consentStatus` other than `'loaded'` (its pre-load fallback answers
|
|
99
|
+
* "everything allowed").
|
|
100
|
+
* - Re-read when the consent data or the privacy script loads
|
|
101
|
+
* (`consentTrackingApiLoaded`, `shopifyCustomerPrivacyApiLoaded`).
|
|
102
|
+
* - On `visitorConsentCollected`, the decision comes from `event.detail`
|
|
103
|
+
* (the API's methods may not exist yet when it fires).
|
|
104
|
+
* - Fails OPEN (`absent`) only when no consent system is present at all.
|
|
105
|
+
*
|
|
106
|
+
* Module-level state (one listener, one wait) is shared by every subscriber.
|
|
107
|
+
*/
|
|
108
|
+
declare const shopifyCustomerPrivacyConsent: PlaybookClientConsent;
|
|
109
|
+
/** TrueVault Polaris's banner cookie (the one Sand Cloud's Blotout/analytics read). */
|
|
110
|
+
declare const TRUEVAULT_CONSENT_COOKIE = "polaris_consent_settings";
|
|
111
|
+
interface TrueVaultConsentOptions {
|
|
112
|
+
/**
|
|
113
|
+
* Decision while the visitor has no `polaris_consent_settings` cookie yet.
|
|
114
|
+
* Default `pending` (closed): nothing analytics runs until Polaris records a
|
|
115
|
+
* decision. `granted` matches an opt-out regime where the absence of a
|
|
116
|
+
* decision means "allowed" (Sand Cloud's own `getPolarisCanTrack`).
|
|
117
|
+
*/
|
|
118
|
+
whenMissing?: Extract<ConsentState, 'pending' | 'granted'>;
|
|
119
|
+
/**
|
|
120
|
+
* Global Privacy Control. Default `follow-banner`: GPC is a sale/sharing
|
|
121
|
+
* opt-out, Playbook doesn't sell data, so GPC alone doesn't deny analytics —
|
|
122
|
+
* only the banner's `analyticsPermitted` decides (Polaris itself keeps
|
|
123
|
+
* `analyticsPermitted` and only flips `notOptedOut` on GPC). `deny`: a store
|
|
124
|
+
* that wants GPC to switch analytics off too.
|
|
125
|
+
*/
|
|
126
|
+
gpc?: 'follow-banner' | 'deny';
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Pure decision shared by server and client. `raw` is the cookie value exactly
|
|
130
|
+
* as stored (URI-encoded JSON or plain JSON); `gpc` is the GPC signal.
|
|
131
|
+
*/
|
|
132
|
+
declare function trueVaultDecision(raw: string | null | undefined, gpc: boolean, { whenMissing, gpc: gpcMode }?: TrueVaultConsentOptions): ConsentState;
|
|
133
|
+
/** TrueVault Polaris: `polaris_consent_settings.analyticsPermitted`, GPC-aware. */
|
|
134
|
+
declare function createTrueVaultConsent(options?: TrueVaultConsentOptions): PlaybookConsentAdapter;
|
|
135
|
+
/** TrueVault with the defaults (closed until a decision; GPC follows the banner). */
|
|
136
|
+
declare const truevaultConsent: PlaybookConsentAdapter;
|
|
3
137
|
|
|
4
138
|
/**
|
|
5
139
|
* Playbook code-test types. Mirrors the ruleset contract served by
|
|
@@ -40,14 +174,14 @@ interface PlaybookRuleset {
|
|
|
40
174
|
/** Why a visitor got this arm (debug/QA; mirrors the platform core's AssignReason). */
|
|
41
175
|
type PlaybookAssignReason = 'preview'
|
|
42
176
|
/** Another test is being previewed on this request: this one serves control. */
|
|
43
|
-
| 'preview-isolated' | '
|
|
177
|
+
| 'preview-isolated' | 'winner' | 'not-running' | 'no-visitor' | 'targeting-device' | 'targeting-visitor-type' | 'namespace' | 'hash-error' | 'coverage' | 'assigned' | 'unknown-test';
|
|
44
178
|
interface PlaybookAssignment {
|
|
45
179
|
arm: string;
|
|
46
180
|
status: PlaybookTestStatus;
|
|
47
181
|
reason: PlaybookAssignReason;
|
|
48
182
|
/** True only when the visitor was bucketed into a RUNNING test. */
|
|
49
183
|
inTest: boolean;
|
|
50
|
-
/** True when the arm comes from a verified `pb_preview` token
|
|
184
|
+
/** True when the arm comes from a verified `pb_preview` token. */
|
|
51
185
|
forced: boolean;
|
|
52
186
|
config: Record<string, unknown>;
|
|
53
187
|
/** Evaluated on the client against the current route (SPA navigation). */
|
|
@@ -61,8 +195,9 @@ interface PlaybookState {
|
|
|
61
195
|
visitorType: PlaybookVisitorType;
|
|
62
196
|
device: PlaybookDevice;
|
|
63
197
|
/**
|
|
64
|
-
* Analytics consent as the server saw it (
|
|
65
|
-
* client re-reads
|
|
198
|
+
* Analytics consent as the server saw it (the server consent source, default
|
|
199
|
+
* `_tracking_consent`). The client re-reads its own live source before any
|
|
200
|
+
* beacon.
|
|
66
201
|
*/
|
|
67
202
|
serverConsent: 'granted' | 'denied' | 'pending' | 'absent';
|
|
68
203
|
/** The store declared a late-loading CMP (closed until it answers). */
|
|
@@ -99,16 +234,6 @@ interface CreatePlaybookOptions {
|
|
|
99
234
|
/** Keeps a background ruleset refresh alive after the response (Workers). */
|
|
100
235
|
waitUntil?: (p: Promise<unknown>) => void;
|
|
101
236
|
fetchImpl?: typeof fetch;
|
|
102
|
-
/**
|
|
103
|
-
* Arms to force regardless of status/targeting (QA). Forced views never
|
|
104
|
-
* expose. The CALLER decides when overrides are trusted (e.g. preview hosts
|
|
105
|
-
* only) — this module applies whatever it is given.
|
|
106
|
-
*
|
|
107
|
-
* Precedence per test: a `pb_preview` token on THIS request > an override
|
|
108
|
-
* from this request (`source: 'request'`) > a `pb_preview` carried by the
|
|
109
|
-
* session cookie > a session override > natural assignment.
|
|
110
|
-
*/
|
|
111
|
-
overrides?: PlaybookOverride[];
|
|
112
237
|
/**
|
|
113
238
|
* The store's CMP may load after first paint (headless, e.g. TrueVault
|
|
114
239
|
* Polaris): with no `_tracking_consent` cookie yet, treat consent as pending
|
|
@@ -116,10 +241,12 @@ interface CreatePlaybookOptions {
|
|
|
116
241
|
* `data-pb-consent="required"`.
|
|
117
242
|
*/
|
|
118
243
|
consentRequired?: boolean;
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
244
|
+
/**
|
|
245
|
+
* Server consent source when the store's CMP doesn't feed Shopify's
|
|
246
|
+
* `_tracking_consent` cookie (e.g. `truevaultConsent`, or a store's own
|
|
247
|
+
* `PlaybookServerConsent`). Replaces the `_tracking_consent` read.
|
|
248
|
+
*/
|
|
249
|
+
consent?: PlaybookServerConsent;
|
|
123
250
|
}
|
|
124
251
|
interface PlaybookServerResult {
|
|
125
252
|
/** Serializable; pass to the client through loader data. */
|
|
@@ -142,7 +269,7 @@ declare function detectGeo(headers: Headers): {
|
|
|
142
269
|
region: string | null;
|
|
143
270
|
};
|
|
144
271
|
declare function detectDevice(userAgent: string | null): PlaybookDevice;
|
|
145
|
-
declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl,
|
|
272
|
+
declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, consentRequired, consent: consentAdapter, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
|
|
146
273
|
|
|
147
274
|
/**
|
|
148
275
|
* Ruleset fetch with an in-memory (per-isolate) cache.
|
|
@@ -158,8 +285,19 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
|
|
|
158
285
|
* shop. Inside it no render touches the network or waits: each one gets the
|
|
159
286
|
* last good copy, or control. The first render after the window retries.
|
|
160
287
|
* This keeps a hanging platform from costing every page request its budget.
|
|
288
|
+
*
|
|
289
|
+
* 0.6.0: the cache itself is `createCachedJsonFetcher`, generic over the
|
|
290
|
+
* payload, so the targeting manifest (`./targeting`) shares the exact same
|
|
291
|
+
* fresh / stale / budget / backoff / warn-once behaviour. The ruleset is its
|
|
292
|
+
* first user; nothing about the ruleset path changed.
|
|
161
293
|
*/
|
|
162
294
|
|
|
295
|
+
/**
|
|
296
|
+
* The ruleset with only its valid rules, or null when the envelope itself is
|
|
297
|
+
* malformed. A single bad rule is DROPPED (its test serves control) rather
|
|
298
|
+
* than discarding every other test; a bad envelope keeps the last good copy.
|
|
299
|
+
*/
|
|
300
|
+
declare function sanitizeRuleset(value: unknown): PlaybookRuleset | null;
|
|
163
301
|
/**
|
|
164
302
|
* Where the ruleset for this render came from (debug/QA):
|
|
165
303
|
* - `memory`: fresh in-memory copy (< 60s).
|
|
@@ -187,48 +325,368 @@ declare function getRulesetWithSource({ platformUrl, shopId, waitUntil, fetchImp
|
|
|
187
325
|
*/
|
|
188
326
|
declare function prefetchRuleset(args: Parameters<typeof getRulesetWithSource>[0]): void;
|
|
189
327
|
|
|
328
|
+
interface CartAttribute {
|
|
329
|
+
key: string;
|
|
330
|
+
value?: string | null;
|
|
331
|
+
}
|
|
332
|
+
interface CartWriteResult {
|
|
333
|
+
ok: boolean;
|
|
334
|
+
/** The cart's attributes after the write, when the response carried them. */
|
|
335
|
+
attributes?: ReadonlyArray<CartAttribute> | null;
|
|
336
|
+
}
|
|
337
|
+
/** Merge `add` into `current` by key (an empty value removes the key). */
|
|
338
|
+
declare function mergeAttributes(current: ReadonlyArray<CartAttribute> | null | undefined, add: ReadonlyArray<CartAttribute>): {
|
|
339
|
+
key: string;
|
|
340
|
+
value: string;
|
|
341
|
+
}[];
|
|
342
|
+
interface CartEndpointOptions {
|
|
343
|
+
/** The store's cart action route. Default `/api/cart` (Pack Hydrogen). */
|
|
344
|
+
endpoint?: string;
|
|
345
|
+
/**
|
|
346
|
+
* The endpoint reads the cart and merges attributes itself (Pack's
|
|
347
|
+
* `/api/cart`): send only the keys being written. Default false: send the
|
|
348
|
+
* full merged list, because Hydrogen's `cart.updateAttributes` REPLACES the
|
|
349
|
+
* whole list and a lone `_pb_vid` would wipe every other attribute.
|
|
350
|
+
*/
|
|
351
|
+
serverMerges?: boolean;
|
|
352
|
+
fetchImpl?: typeof fetch;
|
|
353
|
+
}
|
|
190
354
|
/**
|
|
191
|
-
*
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
|
|
195
|
-
|
|
355
|
+
* Default writer: POSTs to the store's cart endpoint in both shapes Hydrogen
|
|
356
|
+
* stores use (`action` + `attributes` fields, and CartForm's
|
|
357
|
+
* `cartFormInput`). Never throws.
|
|
358
|
+
*/
|
|
359
|
+
declare function createCartAttributeWriter({ endpoint, serverMerges, fetchImpl, }?: CartEndpointOptions): (add: ReadonlyArray<CartAttribute>, current: ReadonlyArray<CartAttribute> | null | undefined) => Promise<CartWriteResult>;
|
|
360
|
+
/** Default re-read: `GET endpoint` → `{cart: {attributes}}`. Null on failure. */
|
|
361
|
+
declare function createCartAttributeReader({ endpoint, fetchImpl, }?: CartEndpointOptions): () => Promise<CartAttribute[] | null>;
|
|
362
|
+
type CartAttributeWriter = ReturnType<typeof createCartAttributeWriter>;
|
|
363
|
+
type CartAttributeReader = ReturnType<typeof createCartAttributeReader>;
|
|
364
|
+
interface CartSyncSnapshot {
|
|
365
|
+
cartId: string | null | undefined;
|
|
366
|
+
attributes: ReadonlyArray<CartAttribute> | null | undefined;
|
|
367
|
+
/** The store's cart status, READ only. Writes wait for `idle` (or none). */
|
|
368
|
+
status?: string | null;
|
|
369
|
+
visitorId: string | null | undefined;
|
|
370
|
+
/** Consent allows it AND the visitor is in at least one running test. */
|
|
371
|
+
eligible: boolean;
|
|
372
|
+
}
|
|
373
|
+
type CartSyncEvent = {
|
|
374
|
+
type: 'scheduled';
|
|
375
|
+
cartId: string;
|
|
376
|
+
} | {
|
|
377
|
+
type: 'written';
|
|
378
|
+
cartId: string;
|
|
379
|
+
ok: boolean;
|
|
380
|
+
} | {
|
|
381
|
+
type: 'restored';
|
|
382
|
+
cartId: string;
|
|
383
|
+
keys: string[];
|
|
384
|
+
ok: boolean;
|
|
385
|
+
} | {
|
|
386
|
+
type: 'capped';
|
|
387
|
+
cartId: string;
|
|
388
|
+
};
|
|
389
|
+
interface CartSyncOptions {
|
|
390
|
+
write: CartAttributeWriter;
|
|
391
|
+
read?: CartAttributeReader;
|
|
392
|
+
maxWritesPerCart?: number;
|
|
393
|
+
idleMs?: number;
|
|
394
|
+
/** Keys another writer owns; restored if a write loses them. */
|
|
395
|
+
protectedKeyPrefixes?: string[];
|
|
396
|
+
onEvent?: (event: CartSyncEvent) => void;
|
|
397
|
+
}
|
|
398
|
+
declare const CART_SYNC_IDLE_MS = 3000;
|
|
399
|
+
declare const MAX_WRITES_PER_CART = 3;
|
|
400
|
+
/**
|
|
401
|
+
* The client write path as a small state machine (no React), so every rule
|
|
402
|
+
* above is unit-testable. Call `update()` with each new cart snapshot.
|
|
403
|
+
*/
|
|
404
|
+
declare function createCartAttributeSync({ write, read, maxWritesPerCart, idleMs, protectedKeyPrefixes, onEvent, }: CartSyncOptions): {
|
|
405
|
+
update(s: CartSyncSnapshot): void;
|
|
406
|
+
dispose(): void;
|
|
407
|
+
/** Test/debug: writes made for the current cart. */
|
|
408
|
+
writesForCart(cartId: string): number;
|
|
409
|
+
};
|
|
410
|
+
/**
|
|
411
|
+
* Returns the cart-create input with `_pb_vid` in its attributes (other
|
|
412
|
+
* attributes kept; an existing `_pb_vid` replaced). `attribute` null → the
|
|
413
|
+
* input unchanged. Use in the store's cart action for `Create`, and for a
|
|
414
|
+
* `LinesAdd` that will create the cart (no cart id yet).
|
|
415
|
+
*/
|
|
416
|
+
declare function withPlaybookCartAttribute<T extends object>(input: T | null | undefined, attribute: CartAttribute | null): T & {
|
|
417
|
+
attributes?: {
|
|
418
|
+
key: string;
|
|
419
|
+
value: string;
|
|
420
|
+
}[];
|
|
421
|
+
};
|
|
422
|
+
|
|
423
|
+
/** Hard ceiling on the hide, in ms. The cloak can be shorter, never longer. */
|
|
424
|
+
declare const CLOAK_MAX_MS = 1500;
|
|
425
|
+
/** The bundle `playbook.js` injects on Hydrogen (CDN sibling of the loader). */
|
|
426
|
+
declare const DEFAULT_EXPERIENCE_SDK_URL = "https://cdn.heyplaybook.com/experience-sdk.js";
|
|
427
|
+
declare const CLOAK_STYLE_ID = "pb-cloak";
|
|
428
|
+
declare const EXPERIENCE_SDK_SCRIPT_ID = "pb-experience-sdk";
|
|
429
|
+
/** What the server decided for this request (`loaderData().cloak`). */
|
|
430
|
+
interface PlaybookCloakConfig {
|
|
431
|
+
/** This path's manifest page key (`product:<handle>`, `home:`, …). */
|
|
432
|
+
targetedPage: string;
|
|
433
|
+
/** `data-pb-shop`: the storefront domain the manifest was read for. */
|
|
434
|
+
shopDomain: string;
|
|
435
|
+
/** `data-pb-api-base`: where the SDK calls the resolver (app proxy). */
|
|
436
|
+
apiBase: string;
|
|
437
|
+
}
|
|
438
|
+
interface PlaybookHeadSnippetOptions {
|
|
439
|
+
/** The store's CSP nonce, put on all three nodes. */
|
|
440
|
+
nonce?: string;
|
|
441
|
+
/** Override the bundle URL (absolute https). Default: the CDN. */
|
|
442
|
+
sdkUrl?: string;
|
|
443
|
+
/** Adds `data-pb-consent="required"` (see the module comment). */
|
|
444
|
+
consentRequired?: boolean;
|
|
445
|
+
/** Shorter hide than 1.5s. Clamped to 100…`CLOAK_MAX_MS`. */
|
|
446
|
+
maxHideMs?: number;
|
|
447
|
+
}
|
|
448
|
+
interface HeadSnippetParts {
|
|
449
|
+
css: string;
|
|
450
|
+
script: string;
|
|
451
|
+
sdk: {
|
|
452
|
+
src: string;
|
|
453
|
+
attrs: Record<string, string>;
|
|
454
|
+
};
|
|
455
|
+
nonce?: string;
|
|
456
|
+
}
|
|
457
|
+
/**
|
|
458
|
+
* Pure: the snippet's parts, or null when nothing should render (no targeted
|
|
459
|
+
* page, or a config missing its shop / api base).
|
|
460
|
+
*/
|
|
461
|
+
declare function buildHeadSnippet(cloak: PlaybookCloakConfig | null | undefined, options?: PlaybookHeadSnippetOptions): HeadSnippetParts | null;
|
|
462
|
+
/**
|
|
463
|
+
* The head nodes as React elements. Renders ONCE: later prop changes (a
|
|
464
|
+
* client-side navigation revalidating the root loader) are ignored, so the
|
|
465
|
+
* hydrated nodes stay exactly as the server sent them.
|
|
466
|
+
*/
|
|
467
|
+
declare const PlaybookCloakHead: react.NamedExoticComponent<PlaybookHeadSnippetOptions & {
|
|
468
|
+
cloak: PlaybookCloakConfig | null | undefined;
|
|
469
|
+
}>;
|
|
470
|
+
/**
|
|
471
|
+
* The cloak + early inject for `<head>`. Place it EARLY in <head> (before the
|
|
472
|
+
* stylesheets and before any `playbook.js` tag):
|
|
196
473
|
*
|
|
197
|
-
*
|
|
198
|
-
* - Read Shopify's Customer Privacy API (`analytics` purpose only, matching
|
|
199
|
-
* the checkout Web Pixel). Never integrate with a CMP directly — any CMP that
|
|
200
|
-
* feeds the API (e.g. TrueVault Polaris) works with no code here.
|
|
201
|
-
* - RENDERING is functional and never gated. The persistent visitor cookie,
|
|
202
|
-
* exposures, events and the cart attribute are ANALYTICS and are gated.
|
|
203
|
-
* - FAIL OPEN only when the API is genuinely absent; CLOSED when it exists and
|
|
204
|
-
* denies, or while a known-present API is still resolving.
|
|
474
|
+
* {playbookHeadSnippet(data.cloak, {nonce})}
|
|
205
475
|
*
|
|
206
|
-
*
|
|
207
|
-
* server). Server: `analyticsConsentFromCookie` reads Shopify's own
|
|
208
|
-
* `_tracking_consent` cookie, the same signal the checkout pixel trusts.
|
|
476
|
+
* Returns null when the page isn't targeted.
|
|
209
477
|
*/
|
|
210
|
-
|
|
478
|
+
declare function playbookHeadSnippet(cloak: PlaybookCloakConfig | null | undefined, options?: PlaybookHeadSnippetOptions): react_jsx_runtime.JSX.Element | null;
|
|
479
|
+
/** The same nodes as an HTML string, for a non-React head. '' when untargeted. */
|
|
480
|
+
declare function playbookHeadSnippetHtml(cloak: PlaybookCloakConfig | null | undefined, options?: PlaybookHeadSnippetOptions): string;
|
|
481
|
+
|
|
482
|
+
/** The env keys the kit reads (all optional). */
|
|
483
|
+
interface PlaybookEnv {
|
|
484
|
+
PUBLIC_PLAYBOOK_SHOP_ID?: string;
|
|
485
|
+
PLAYBOOK_PLATFORM_URL?: string;
|
|
486
|
+
PLAYBOOK_TESTS_DISABLED?: string;
|
|
487
|
+
/** 0.6.0: storefront domain for the targeting manifest (see `shopDomain`). */
|
|
488
|
+
PUBLIC_PLAYBOOK_SHOP_DOMAIN?: string;
|
|
489
|
+
}
|
|
490
|
+
interface CreatePlaybookContextOptions {
|
|
491
|
+
request: Request;
|
|
492
|
+
/** The worker env; any object carrying the keys above. */
|
|
493
|
+
env?: PlaybookEnv | Record<string, unknown> | null;
|
|
494
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
495
|
+
/** Overrides `env.PUBLIC_PLAYBOOK_SHOP_ID`. */
|
|
496
|
+
shopId?: string | null;
|
|
497
|
+
/** Overrides `env.PLAYBOOK_PLATFORM_URL`. */
|
|
498
|
+
platformUrl?: string | null;
|
|
499
|
+
/** Overrides `env.PLAYBOOK_TESTS_DISABLED`. */
|
|
500
|
+
disabled?: boolean;
|
|
501
|
+
/** See `createPlaybook({consentRequired})` (Shopify consent path only). */
|
|
502
|
+
consentRequired?: boolean;
|
|
503
|
+
/**
|
|
504
|
+
* Server consent source: a `PlaybookServerConsent` (e.g. a store's CMS
|
|
505
|
+
* session record) or a full adapter (e.g. `truevaultConsent`, then pass the
|
|
506
|
+
* same one to the client). Default: Shopify's `_tracking_consent` cookie.
|
|
507
|
+
*/
|
|
508
|
+
consent?: PlaybookServerConsent;
|
|
509
|
+
/**
|
|
510
|
+
* 0.6.0: `reconcileCartAttributes` also puts back the EXPERIENCE-test cart
|
|
511
|
+
* attributes (`pb_exp__`, `pb_vid__`) when another script wiped them, for a
|
|
512
|
+
* visitor the browser SDK has shown an experience test. Fill-only; see
|
|
513
|
+
* `./experience-attribution`. Default `true`; `false` restores 0.5.0.
|
|
514
|
+
*/
|
|
515
|
+
experienceAttribution?: boolean;
|
|
516
|
+
/**
|
|
517
|
+
* 0.6.0: read the platform's targeting manifest in `loaderData()` so the
|
|
518
|
+
* head can cloak + early-inject on a page an all-traffic experience test
|
|
519
|
+
* targets (`loaderData().cloak`, `playbookHeadSnippet`). Default `true`.
|
|
520
|
+
*/
|
|
521
|
+
cloak?: boolean;
|
|
522
|
+
/**
|
|
523
|
+
* 0.6.0: the storefront DOMAIN the targeting manifest is keyed by (its
|
|
524
|
+
* `?shop=`; the Playbook UUID doesn't work there). Overrides
|
|
525
|
+
* `env.PUBLIC_PLAYBOOK_SHOP_DOMAIN`; default the request's hostname, the
|
|
526
|
+
* same fallback `playbook.js` uses on a headless store.
|
|
527
|
+
*/
|
|
528
|
+
shopDomain?: string | null;
|
|
529
|
+
/**
|
|
530
|
+
* 0.6.0: the experience SDK's `data-pb-api-base`. Default
|
|
531
|
+
* `<request origin>/apps/playbook` (the store's app-proxy route), which is
|
|
532
|
+
* what `playbook.js` passes when it's loaded from `/apps/playbook/sdk`.
|
|
533
|
+
*/
|
|
534
|
+
apiBase?: string | null;
|
|
535
|
+
fetchImpl?: typeof fetch;
|
|
536
|
+
}
|
|
537
|
+
interface PlaybookLoaderData {
|
|
538
|
+
/** Store-test state for `<PlaybookRoot state>` / `<PlaybookHead state>`. */
|
|
539
|
+
playbook: PlaybookState | null;
|
|
540
|
+
/** For `<PlaybookHead hasPlaybookParams>` (anti-flicker). */
|
|
541
|
+
hasPlaybookParams: boolean;
|
|
542
|
+
/**
|
|
543
|
+
* 0.6.0: this path's manifest page key (`product:<handle>`, `home:`, …)
|
|
544
|
+
* when an all-traffic experience test targets it, else null. Null on any
|
|
545
|
+
* manifest failure or timeout, on `pbk`/`_pv`/preview visits, and never
|
|
546
|
+
* set by utm params alone.
|
|
547
|
+
*/
|
|
548
|
+
targetedPage: string | null;
|
|
549
|
+
/** 0.6.0: pass to `playbookHeadSnippet(cloak, {nonce})`. Null = no cloak. */
|
|
550
|
+
cloak: PlaybookCloakConfig | null;
|
|
551
|
+
}
|
|
552
|
+
interface PlaybookRequestContext {
|
|
553
|
+
readonly shopId: string | null;
|
|
554
|
+
readonly platformUrl: string;
|
|
555
|
+
/** True when the kill switch is on (or there is no shop id). */
|
|
556
|
+
readonly disabled: boolean;
|
|
557
|
+
get(): Promise<PlaybookServerResult | null>;
|
|
558
|
+
loaderData(): Promise<PlaybookLoaderData>;
|
|
559
|
+
cartAttribute(): CartAttribute | null;
|
|
560
|
+
/**
|
|
561
|
+
* The visitor id this request may stamp on the cart as `_pb_vid`: analytics
|
|
562
|
+
* consent granted (or no consent system and `consentRequired` off), read
|
|
563
|
+
* from `_pb_visitor_id` then `_pb_session_vid`. Never minted; null when
|
|
564
|
+
* disabled, without consent, or without an id. No ruleset fetch.
|
|
565
|
+
*/
|
|
566
|
+
cartVisitorId(): string | null;
|
|
567
|
+
/**
|
|
568
|
+
* The cart's full attribute list with `_pb_vid` added, corrected or removed
|
|
569
|
+
* (consent withdrawn / no id), every other attribute kept; `null` when the
|
|
570
|
+
* cart is already right, or when Playbook is disabled (the cart is left
|
|
571
|
+
* untouched). Call after EVERY cart action with the cart as it now stands.
|
|
572
|
+
*
|
|
573
|
+
* 0.6.0: also fills a missing `pb_exp__` / `pb_vid__` (experience tests) for
|
|
574
|
+
* a visitor with an experience exposure, and removes them on an explicit
|
|
575
|
+
* denial. Still one list, so still at most one write.
|
|
576
|
+
*/
|
|
577
|
+
reconcileCartAttributes(current: ReadonlyArray<{
|
|
578
|
+
key: string;
|
|
579
|
+
value?: string | null;
|
|
580
|
+
}> | null | undefined): {
|
|
581
|
+
key: string;
|
|
582
|
+
value: string;
|
|
583
|
+
}[] | null;
|
|
584
|
+
/** APPEND this request's Playbook cookies to `headers`. Never throws. */
|
|
585
|
+
appendCookies(headers: Headers): Promise<void>;
|
|
586
|
+
/**
|
|
587
|
+
* Returns the response with this request's Playbook cookies appended
|
|
588
|
+
* (re-wrapping it when its headers are immutable, e.g. `Response.redirect`).
|
|
589
|
+
* A redirect never waits on a still-pending resolution: its cookies are
|
|
590
|
+
* skipped and the next request sets them.
|
|
591
|
+
*/
|
|
592
|
+
finalize(response: Response): Promise<Response>;
|
|
593
|
+
}
|
|
594
|
+
declare function createPlaybookContext({ request, env, waitUntil, shopId: shopIdOption, platformUrl: platformUrlOption, disabled: disabledOption, consentRequired, consent, experienceAttribution, cloak: cloakOption, shopDomain: shopDomainOption, apiBase: apiBaseOption, fetchImpl, }: CreatePlaybookContextOptions): PlaybookRequestContext;
|
|
211
595
|
/**
|
|
212
|
-
*
|
|
213
|
-
*
|
|
214
|
-
*
|
|
596
|
+
* Wrapper form: creates the context, runs the store's handler with it, then
|
|
597
|
+
* finalizes whatever response the handler returns (incl. a redirect built
|
|
598
|
+
* from a 404). The handler must still put `playbook` on its load context.
|
|
215
599
|
*/
|
|
216
|
-
declare function
|
|
217
|
-
|
|
218
|
-
declare
|
|
219
|
-
/**
|
|
220
|
-
declare
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
600
|
+
declare function withPlaybook(options: CreatePlaybookContextOptions, handler: (playbook: PlaybookRequestContext) => Promise<Response>): Promise<Response>;
|
|
601
|
+
|
|
602
|
+
declare const DEFAULT_SDK_URL = "https://cdn.heyplaybook.com/playbook.js";
|
|
603
|
+
/** First-party proxy prefix (the `/apps/playbook/*` route). */
|
|
604
|
+
declare const DEFAULT_PROXY_ENDPOINT = "/apps/playbook";
|
|
605
|
+
/** The reveal script, byte-compatible with the hand-wired integrations. */
|
|
606
|
+
declare function revealScript(hasPlaybookParams: boolean): string;
|
|
607
|
+
interface PlaybookHeadProps {
|
|
608
|
+
/** Playbook shop UUID (`PUBLIC_PLAYBOOK_SHOP_ID`). Falsy → renders nothing. */
|
|
609
|
+
shopId: string | null | undefined;
|
|
610
|
+
/**
|
|
611
|
+
* Where `playbook.js` sends API calls. Default `/apps/playbook` (first-party
|
|
612
|
+
* proxy); pass `https://www.heyplaybook.com` to go direct.
|
|
613
|
+
*/
|
|
614
|
+
apiEndpoint?: string;
|
|
615
|
+
sdkUrl?: string;
|
|
616
|
+
/** From `context.playbook.loaderData()` (or `hasPlaybookParams(request.url)`). */
|
|
617
|
+
hasPlaybookParams?: boolean;
|
|
618
|
+
/** Store-test state from the root loader; its visitor id is seeded. */
|
|
619
|
+
state?: PlaybookState | null;
|
|
620
|
+
/** Explicit visitor id (overrides `state`). Non-UUID values are ignored. */
|
|
621
|
+
visitorId?: string | null;
|
|
622
|
+
/** CSP nonce for the inline scripts/style, when the store sets a CSP. */
|
|
623
|
+
nonce?: string;
|
|
624
|
+
}
|
|
625
|
+
declare function PlaybookHead({ shopId, apiEndpoint, sdkUrl, hasPlaybookParams, state, visitorId, nonce, }: PlaybookHeadProps): react_jsx_runtime.JSX.Element | null;
|
|
626
|
+
|
|
627
|
+
declare function manifestUrl(platformUrl: string, shopDomain: string): string;
|
|
224
628
|
/**
|
|
225
|
-
*
|
|
226
|
-
*
|
|
227
|
-
*
|
|
228
|
-
* known payload shapes (`con.CMP.a` = "1"/"0"/"" and `purposes.a` boolean);
|
|
229
|
-
* anything unparseable is `pending` (closed), never granted.
|
|
629
|
+
* The manifest's `pages` as clean strings, or null when the envelope is not
|
|
630
|
+
* a manifest. A manifest without `pages` (an older platform) is `[]` — valid,
|
|
631
|
+
* nothing targeted. Non-string entries are dropped.
|
|
230
632
|
*/
|
|
231
|
-
declare function
|
|
633
|
+
declare function sanitizeManifestPages(value: unknown): string[] | null;
|
|
634
|
+
/**
|
|
635
|
+
* The shop's all-traffic page keys, or `null` when the read is not healthy
|
|
636
|
+
* (failure, timeout, backoff, last-good during an outage) — the caller must
|
|
637
|
+
* then NOT hide. Never throws.
|
|
638
|
+
*/
|
|
639
|
+
declare function getTargetedPages({ platformUrl, shopDomain, waitUntil, fetchImpl, }: {
|
|
640
|
+
platformUrl: string;
|
|
641
|
+
shopDomain: string;
|
|
642
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
643
|
+
fetchImpl?: typeof fetch;
|
|
644
|
+
}): Promise<{
|
|
645
|
+
pages: string[] | null;
|
|
646
|
+
source: RulesetSource;
|
|
647
|
+
}>;
|
|
648
|
+
/**
|
|
649
|
+
* The manifest page key for a storefront path — a byte-for-byte port of
|
|
650
|
+
* `targetPageKey` in shared/src/targeting/index.ts (the same function the
|
|
651
|
+
* `playbook.js` loader and the experience SDK use):
|
|
652
|
+
* `product:<handle>` (also under `/collections/<c>/products/<p>`),
|
|
653
|
+
* `collection:<handle>`, `home:`, `page:<handle>` for `/pages/<handle>`,
|
|
654
|
+
* `page:cart`, `page:<path>` for any other storefront path; null for an
|
|
655
|
+
* untargetable path. A leading locale segment (`/en-us`, `/fr`) and a
|
|
656
|
+
* trailing slash are stripped; handles are URI-decoded and lowercased.
|
|
657
|
+
*/
|
|
658
|
+
declare function targetPageKey(pathname: string): string | null;
|
|
659
|
+
/**
|
|
660
|
+
* This path's page key when the manifest serves it to all traffic, else null.
|
|
661
|
+
* Same matching as `manifestMatchesPage` (shared): exact key, or a key ending
|
|
662
|
+
* in `*` by prefix (`"*"`, `"product:*"`, `"product:the-weekender-in-*"`).
|
|
663
|
+
*/
|
|
664
|
+
declare function matchTargetedPage(pages: readonly string[] | null | undefined, pathname: string): string | null;
|
|
665
|
+
|
|
666
|
+
/**
|
|
667
|
+
* Store-specific "why not in test" text for the QA panel. Return a string to
|
|
668
|
+
* show it (it wins over the generic reason), or null to fall back to the
|
|
669
|
+
* generic reason. Runs in the browser; must not throw (errors are ignored).
|
|
670
|
+
*/
|
|
671
|
+
type PlaybookDebugExplain = (testKey: string, assignment: PlaybookAssignment, pathname: string) => string | null | undefined;
|
|
672
|
+
/** `<PlaybookRoot debug>` options. */
|
|
673
|
+
interface PlaybookDebugOptions {
|
|
674
|
+
/** Force allow/deny; default: preview hosts or a verified preview token. */
|
|
675
|
+
allowed?: boolean;
|
|
676
|
+
/** Test keys this storefront has code for (others are labelled as such). */
|
|
677
|
+
implementedTests?: string[];
|
|
678
|
+
/** Store-specific eligibility text (e.g. "not a towel product"). */
|
|
679
|
+
explain?: PlaybookDebugExplain;
|
|
680
|
+
}
|
|
681
|
+
/** May the panel open on this page? */
|
|
682
|
+
declare function debugPanelAllowed(state: PlaybookState | null | undefined, hostname: string, allowed?: boolean): boolean;
|
|
683
|
+
declare function PlaybookDebugPanel({ state, location, allowed, implementedTests, explain, }: {
|
|
684
|
+
state: PlaybookState | null | undefined;
|
|
685
|
+
location: {
|
|
686
|
+
pathname: string;
|
|
687
|
+
search?: string;
|
|
688
|
+
};
|
|
689
|
+
} & PlaybookDebugOptions): react_jsx_runtime.JSX.Element | null;
|
|
232
690
|
|
|
233
691
|
/**
|
|
234
692
|
* The standard events — ONE taxonomy for every store (GROWTH-TESTS.md "The
|
|
@@ -244,6 +702,17 @@ interface PlaybookStoreContext {
|
|
|
244
702
|
locale?: string | null;
|
|
245
703
|
isLoggedIn?: boolean | null;
|
|
246
704
|
}
|
|
705
|
+
/**
|
|
706
|
+
* GA4 / GTM forwarding of exposures. OFF by default since 0.5.0 (a store that
|
|
707
|
+
* also runs another testing tool's `view_experiment` — e.g. Pack tests — would
|
|
708
|
+
* get two tools' experiments mixed in GA4). `true` or `{}` turns it on;
|
|
709
|
+
* `{eventName}` turns it on under another event name (default
|
|
710
|
+
* `view_experiment`); `false` keeps it off.
|
|
711
|
+
*/
|
|
712
|
+
type PlaybookDataLayerOption = boolean | {
|
|
713
|
+
eventName?: string;
|
|
714
|
+
};
|
|
715
|
+
declare const DEFAULT_DATALAYER_EVENT = "view_experiment";
|
|
247
716
|
interface TrackedEntry {
|
|
248
717
|
at: string;
|
|
249
718
|
kind: 'exposure' | 'event';
|
|
@@ -289,6 +758,141 @@ interface TrackOptions {
|
|
|
289
758
|
*/
|
|
290
759
|
declare function playbookTrack(event: StandardEvent, rawProps?: Record<string, unknown>, scope?: TrackScope, { oncePerSession, beacon }?: TrackOptions): number;
|
|
291
760
|
|
|
761
|
+
/** The sitewide A/A test key the sentinel exposes for. */
|
|
762
|
+
declare const AA_SITEWIDE_TEST = "aa-sitewide";
|
|
763
|
+
/** What the kit needs from the store's cart. READ-only: no setters. */
|
|
764
|
+
interface PlaybookCartAdapter {
|
|
765
|
+
cartId: string | null | undefined;
|
|
766
|
+
attributes: ReadonlyArray<CartAttribute> | null | undefined;
|
|
767
|
+
/** The store's cart status (writes wait for `idle`). Never written. */
|
|
768
|
+
status?: string | null;
|
|
769
|
+
/** Cart action route for the default writer/reader. Default `/api/cart`. */
|
|
770
|
+
endpoint?: string;
|
|
771
|
+
/** The endpoint merges attributes server-side (Pack `/api/cart`). */
|
|
772
|
+
serverMerges?: boolean;
|
|
773
|
+
/** Replace the default writer (must not touch the store's cart state). */
|
|
774
|
+
write?: CartAttributeWriter;
|
|
775
|
+
/** Replace the default re-read (used to confirm `_ig*` keys survived). */
|
|
776
|
+
read?: CartAttributeReader;
|
|
777
|
+
}
|
|
778
|
+
interface PlaybookRootProps {
|
|
779
|
+
state: PlaybookState | null | undefined;
|
|
780
|
+
location: {
|
|
781
|
+
pathname: string;
|
|
782
|
+
search?: string;
|
|
783
|
+
hash?: string;
|
|
784
|
+
};
|
|
785
|
+
/** Router navigate; used only to restore `?pb_preview=` inside Playbook's frame. */
|
|
786
|
+
navigate?: (to: string, options: {
|
|
787
|
+
replace: true;
|
|
788
|
+
preventScrollReset: true;
|
|
789
|
+
}) => void;
|
|
790
|
+
/**
|
|
791
|
+
* Client `_pb_vid` sync. `null` turns it off — do that when the server owns
|
|
792
|
+
* `_pb_vid` (`context.playbook.reconcileCartAttributes` in the cart action).
|
|
793
|
+
*/
|
|
794
|
+
cart?: PlaybookCartAdapter | null;
|
|
795
|
+
/**
|
|
796
|
+
* Browser consent: a `PlaybookClientConsent` or a full adapter. Default:
|
|
797
|
+
* Shopify's Customer Privacy API (`shopifyCustomerPrivacyConsent`).
|
|
798
|
+
*/
|
|
799
|
+
consent?: PlaybookClientConsent;
|
|
800
|
+
storeContext?: PlaybookStoreContext;
|
|
801
|
+
/**
|
|
802
|
+
* The store's own CMS/editor preview (e.g. Pack customizer): no cart write,
|
|
803
|
+
* no A/A exposure.
|
|
804
|
+
*/
|
|
805
|
+
editorPreview?: boolean;
|
|
806
|
+
/** Render the `aa-sitewide` sentinel (default true; inert without that test). */
|
|
807
|
+
aaSentinel?: boolean;
|
|
808
|
+
/**
|
|
809
|
+
* QA panel: force allow/deny, the test keys this store has code for, and
|
|
810
|
+
* `explain` for store-specific "why not in test" text.
|
|
811
|
+
*/
|
|
812
|
+
debug?: PlaybookDebugOptions;
|
|
813
|
+
/**
|
|
814
|
+
* GA4 `view_experiment` dataLayer push per exposure. OFF by default since
|
|
815
|
+
* 0.5.0; `true` / `{eventName}` turns it on.
|
|
816
|
+
*/
|
|
817
|
+
dataLayer?: PlaybookDataLayerOption;
|
|
818
|
+
/** A verified preview shows its arm even off-target (default false). */
|
|
819
|
+
previewIgnoresTargeting?: boolean;
|
|
820
|
+
/** Observe cart-sync decisions (debug/logging). */
|
|
821
|
+
onCartSyncEvent?: (event: CartSyncEvent) => void;
|
|
822
|
+
exposureUrl?: string;
|
|
823
|
+
eventUrl?: string;
|
|
824
|
+
supportedEvents?: string[];
|
|
825
|
+
children: ReactNode;
|
|
826
|
+
}
|
|
827
|
+
/** Any running (non-forced) test the visitor is bucketed into. */
|
|
828
|
+
declare function visitorInRunningTest(state: PlaybookState | null | undefined): boolean;
|
|
829
|
+
/**
|
|
830
|
+
* A/A sentinel: invisible and IDENTICAL in both arms, so `aa-sitewide` can only
|
|
831
|
+
* measure the pipeline itself. Always in the viewport, out of layout flow.
|
|
832
|
+
* With no such rule (or not running) nothing is sent.
|
|
833
|
+
*/
|
|
834
|
+
declare function PlaybookAAExposure({ testKey }: {
|
|
835
|
+
testKey?: string;
|
|
836
|
+
}): react_jsx_runtime.JSX.Element;
|
|
837
|
+
declare function PlaybookRoot({ state, location, navigate, cart, consent, storeContext, editorPreview, aaSentinel, debug, dataLayer, previewIgnoresTargeting, onCartSyncEvent, exposureUrl, eventUrl, supportedEvents, children, }: PlaybookRootProps): react_jsx_runtime.JSX.Element;
|
|
838
|
+
|
|
839
|
+
interface Props {
|
|
840
|
+
/** For the console warning only. */
|
|
841
|
+
name: string;
|
|
842
|
+
children?: ReactNode;
|
|
843
|
+
}
|
|
844
|
+
declare class PlaybookBoundary extends Component<Props, {
|
|
845
|
+
failed: boolean;
|
|
846
|
+
}> {
|
|
847
|
+
state: {
|
|
848
|
+
failed: boolean;
|
|
849
|
+
};
|
|
850
|
+
static getDerivedStateFromError(): {
|
|
851
|
+
failed: boolean;
|
|
852
|
+
};
|
|
853
|
+
componentDidCatch(error: unknown): void;
|
|
854
|
+
render(): string | number | bigint | boolean | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
|
|
855
|
+
}
|
|
856
|
+
|
|
857
|
+
type PlatformUrlOption = string | null | undefined | ((args: ProxyArgs) => string | null | undefined);
|
|
858
|
+
interface ProxyArgs {
|
|
859
|
+
request: Request;
|
|
860
|
+
/** The route's load context; `context.env.PLAYBOOK_PLATFORM_URL` is read by default. */
|
|
861
|
+
context?: unknown;
|
|
862
|
+
}
|
|
863
|
+
interface PlaybookProxyOptions {
|
|
864
|
+
/** Default: `context.env.PLAYBOOK_PLATFORM_URL`, else heyplaybook.com. */
|
|
865
|
+
platformUrl?: PlatformUrlOption;
|
|
866
|
+
timeoutMs?: number;
|
|
867
|
+
maxBodyBytes?: number;
|
|
868
|
+
fetchImpl?: typeof fetch;
|
|
869
|
+
}
|
|
870
|
+
/** `/apps/playbook/api/x?y` → `{platform}/api/x?y`; other paths → `/api/<path>`. */
|
|
871
|
+
declare function playbookBackendUrl(requestUrl: string, platformUrl: string): string;
|
|
872
|
+
declare function createPlaybookProxyHandler({ platformUrl, timeoutMs, maxBodyBytes, fetchImpl, }?: PlaybookProxyOptions): {
|
|
873
|
+
loader: (args: ProxyArgs) => Promise<Response>;
|
|
874
|
+
action: (args: ProxyArgs) => Promise<Response>;
|
|
875
|
+
};
|
|
876
|
+
|
|
877
|
+
/** Small isomorphic predicates shared by the server helper and the client. */
|
|
878
|
+
/**
|
|
879
|
+
* The legacy `playbook.js` loader is about to swap content in (landing
|
|
880
|
+
* experiences, editor/brand previews): hide the page until it reveals it.
|
|
881
|
+
* Same four markers the hand-wired integrations checked.
|
|
882
|
+
*/
|
|
883
|
+
declare function hasPlaybookParams(url: string | URL): boolean;
|
|
884
|
+
/**
|
|
885
|
+
* Kill switch: `PLAYBOOK_TESTS_DISABLED=1` (or `true`) turns off ONLY the
|
|
886
|
+
* store-test kit — assignment, visitor cookies, the cart attribute, exposures
|
|
887
|
+
* and events. The legacy `playbook.js` loader keeps running.
|
|
888
|
+
*/
|
|
889
|
+
declare function isKillSwitchOn(value: string | null | undefined): boolean;
|
|
890
|
+
/**
|
|
891
|
+
* Non-production hosts where the QA panel may open from `?pb_debug=1`:
|
|
892
|
+
* Oxygen previews (`*.myshopify.dev`), Shopify previews, workers.dev and local.
|
|
893
|
+
*/
|
|
894
|
+
declare function isPreviewHost(hostname: string): boolean;
|
|
895
|
+
|
|
292
896
|
declare const DEFAULT_EXPOSURE_URL = "/apps/playbook/api/storefront/tests/exposure";
|
|
293
897
|
declare const DEFAULT_EVENT_URL = "/apps/playbook/api/storefront/tests/event";
|
|
294
898
|
/** Live analytics consent: granted / denied / pending / absent (API absent). */
|
|
@@ -310,9 +914,10 @@ interface PlaybookVariant {
|
|
|
310
914
|
* state, so SSR and hydration render the same arm (no flicker).
|
|
311
915
|
*
|
|
312
916
|
* `eligible: false` (e.g. "not a towel product") → control, not in test.
|
|
313
|
-
* A forced arm (
|
|
314
|
-
*
|
|
315
|
-
*
|
|
917
|
+
* A forced arm (a verified `pb_preview` link) skips status and traffic split
|
|
918
|
+
* but still respects targeting: a towel arm forced on a towel page must not
|
|
919
|
+
* follow the session onto a bedding page. A store that wants previews to show
|
|
920
|
+
* the arm everywhere passes `<PlaybookRoot previewIgnoresTargeting>`.
|
|
316
921
|
*/
|
|
317
922
|
declare function usePlaybookVariant(testKey: string, { eligible }?: {
|
|
318
923
|
eligible?: boolean;
|
|
@@ -347,7 +952,7 @@ declare function usePreviewParamRedirect(location: {
|
|
|
347
952
|
hash: string;
|
|
348
953
|
}): string | null;
|
|
349
954
|
|
|
350
|
-
declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, children, }: {
|
|
955
|
+
declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, consent: consentAdapter, dataLayer, previewIgnoresTargeting, children, }: {
|
|
351
956
|
state: PlaybookState | null | undefined;
|
|
352
957
|
/** Current route pathname (re-render on navigation so path targeting updates). */
|
|
353
958
|
pathname: string;
|
|
@@ -357,6 +962,25 @@ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supp
|
|
|
357
962
|
supportedEvents?: string[];
|
|
358
963
|
/** Market / locale / login state, for the exposure context. */
|
|
359
964
|
storeContext?: PlaybookStoreContext;
|
|
965
|
+
/**
|
|
966
|
+
* Browser consent source (a `PlaybookClientConsent`, or a full adapter).
|
|
967
|
+
* Default: Shopify's Customer Privacy API (`shopifyCustomerPrivacyConsent`).
|
|
968
|
+
* Keep it closed on the same "unknown" states as the server source.
|
|
969
|
+
*/
|
|
970
|
+
consent?: PlaybookClientConsent;
|
|
971
|
+
/**
|
|
972
|
+
* Forward each exposure to `window.dataLayer` as GA4 `view_experiment`.
|
|
973
|
+
* OFF by default since 0.5.0; `true` / `{}` turns it on, `{eventName}`
|
|
974
|
+
* renames it.
|
|
975
|
+
*/
|
|
976
|
+
dataLayer?: PlaybookDataLayerOption;
|
|
977
|
+
/**
|
|
978
|
+
* A verified preview (`pb_preview`) shows the forced arm even where the
|
|
979
|
+
* test doesn't apply (`eligible: false` or an off-target path). Default
|
|
980
|
+
* false: the forced arm respects targeting, so an arm previewed on a towel
|
|
981
|
+
* page doesn't follow the reviewer onto a bedding page.
|
|
982
|
+
*/
|
|
983
|
+
previewIgnoresTargeting?: boolean;
|
|
360
984
|
children: ReactNode;
|
|
361
985
|
}): react_jsx_runtime.JSX.Element;
|
|
362
986
|
/** Component form of `usePlaybookExposure` for wrapping an existing element. */
|
|
@@ -373,7 +997,8 @@ declare function PlaybookExposure({ testKey, variant, enabled, children, }: {
|
|
|
373
997
|
* does for the SDK (so both write the same keys the same way):
|
|
374
998
|
*
|
|
375
999
|
* granted / no CMP → `_pb_visitor_id` cookie, 365d (promotes a session id)
|
|
376
|
-
*
|
|
1000
|
+
* pending → sessionStorage only; an existing cookie is left alone
|
|
1001
|
+
* denied → sessionStorage only; any cookie is EXPIRED
|
|
377
1002
|
*
|
|
378
1003
|
* sessionStorage `_pb_visitor_id` is always seeded with the server's id so the
|
|
379
1004
|
* SDK's helper (which reads sessionStorage under denial) uses the same value.
|
|
@@ -383,10 +1008,14 @@ declare function syncVisitorId(visitorId: string, consent: ConsentState): void;
|
|
|
383
1008
|
/**
|
|
384
1009
|
* Inline script for the document <head>, BEFORE the SDK script: seeds
|
|
385
1010
|
* sessionStorage so `playbook.js` resolves the same visitor id even when it
|
|
386
|
-
* runs before hydration.
|
|
387
|
-
*
|
|
1011
|
+
* runs before hydration.
|
|
1012
|
+
*
|
|
1013
|
+
* The id comes from a request cookie the browser controls and is interpolated
|
|
1014
|
+
* into an inline <script>, so ONLY the UUID shape Playbook mints is accepted;
|
|
1015
|
+
* anything else returns '' (render no script) and a tampered cookie can never
|
|
1016
|
+
* break out of the tag.
|
|
388
1017
|
*/
|
|
389
|
-
declare function visitorSeedScript(visitorId: string): string;
|
|
1018
|
+
declare function visitorSeedScript(visitorId: string | null | undefined): string;
|
|
390
1019
|
|
|
391
1020
|
declare function usePageEngagement(pathname: string, enabled: boolean): void;
|
|
392
1021
|
|
|
@@ -408,7 +1037,7 @@ declare const SESSION_VISITOR_COOKIE = "_pb_session_vid";
|
|
|
408
1037
|
/** Retired pilot cookie; migrated on first read, then expired. */
|
|
409
1038
|
declare const LEGACY_VISITOR_COOKIE = "pb_vid";
|
|
410
1039
|
|
|
411
|
-
type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'other';
|
|
1040
|
+
type AddToCartSource = 'pdp' | 'quick_add' | 'cart_upsell' | 'cross_sell' | 'other';
|
|
412
1041
|
declare function setNextAddSource(source: AddToCartSource): void;
|
|
413
1042
|
declare function takeAddSource(): AddToCartSource;
|
|
414
1043
|
interface AddedLineInput {
|
|
@@ -426,6 +1055,31 @@ interface CartLineSnapshot {
|
|
|
426
1055
|
};
|
|
427
1056
|
};
|
|
428
1057
|
}
|
|
1058
|
+
type CartLinesLike = CartLineSnapshot[] | {
|
|
1059
|
+
nodes?: CartLineSnapshot[];
|
|
1060
|
+
edges?: {
|
|
1061
|
+
node: CartLineSnapshot;
|
|
1062
|
+
}[];
|
|
1063
|
+
} | null | undefined;
|
|
1064
|
+
/**
|
|
1065
|
+
* The lines an add request carried. Accepts the lines array itself, or the
|
|
1066
|
+
* cart request's FormData in either Hydrogen shape: `action` + `lines` /
|
|
1067
|
+
* `cart` fields (Pack's `/api/cart`), or CartForm's `cartFormInput`.
|
|
1068
|
+
*/
|
|
1069
|
+
declare function addedLinesFrom(input: AddedLineInput[] | FormData | null | undefined): AddedLineInput[];
|
|
1070
|
+
/**
|
|
1071
|
+
* The store's ONE add-to-cart touchpoint. Call it after a SUCCESSFUL add
|
|
1072
|
+
* (no user errors), with the lines that were added (array or the request's
|
|
1073
|
+
* FormData) and the cart the mutation returned. `source` omitted → the one set
|
|
1074
|
+
* by `setNextAddSource` (taken now), else `other`. No-op without consent or
|
|
1075
|
+
* outside a running test. Never throws.
|
|
1076
|
+
*/
|
|
1077
|
+
declare function trackAddToCart(source: AddToCartSource | null | undefined, { lines, cart, }: {
|
|
1078
|
+
lines: AddedLineInput[] | FormData | null | undefined;
|
|
1079
|
+
cart: {
|
|
1080
|
+
lines?: CartLinesLike;
|
|
1081
|
+
} | null | undefined | unknown;
|
|
1082
|
+
}): void;
|
|
429
1083
|
/** One `add_to_cart` per added line. Never throws. */
|
|
430
1084
|
declare function trackAddToCartLines(lines: AddedLineInput[], cartLines: CartLineSnapshot[], source: AddToCartSource): void;
|
|
431
1085
|
|
|
@@ -440,6 +1094,74 @@ declare function cartHasPlaybookAttribute(attributes: ReadonlyArray<{
|
|
|
440
1094
|
key: string;
|
|
441
1095
|
value?: string | null;
|
|
442
1096
|
}> | null | undefined, visitorId: string): boolean;
|
|
1097
|
+
/**
|
|
1098
|
+
* The cart's FULL attribute list with `_pb_vid` reconciled to `visitorId`:
|
|
1099
|
+
* added when missing, corrected when stale (or duplicated), removed when
|
|
1100
|
+
* `visitorId` is null (no id, or consent withdrawn). Every other attribute is
|
|
1101
|
+
* kept as-is, in order. Returns `null` when the cart is already right, so the
|
|
1102
|
+
* caller skips the mutation.
|
|
1103
|
+
*
|
|
1104
|
+
* Pure: it never mints an id. Pass the result to a REPLACE-style write
|
|
1105
|
+
* (Hydrogen's `cart.updateAttributes`), which is why the whole list comes
|
|
1106
|
+
* back rather than just `_pb_vid`. A null/empty value on another key is
|
|
1107
|
+
* written back as `''`.
|
|
1108
|
+
*/
|
|
1109
|
+
declare function reconcilePlaybookCartAttribute(current: ReadonlyArray<{
|
|
1110
|
+
key: string;
|
|
1111
|
+
value?: string | null;
|
|
1112
|
+
}> | null | undefined, visitorId: string | null | undefined): {
|
|
1113
|
+
key: string;
|
|
1114
|
+
value: string;
|
|
1115
|
+
}[] | null;
|
|
1116
|
+
|
|
1117
|
+
/** The SDK's exposure-list cookie (30 days). */
|
|
1118
|
+
declare const EXPOSURE_COOKIE = "_pb_exp";
|
|
1119
|
+
/** Cart attribute the `orders/paid` webhook decodes as the exposure list. */
|
|
1120
|
+
declare const EXPOSURE_CART_ATTRIBUTE = "pb_exp__";
|
|
1121
|
+
/** Cart attribute carrying the long-lived visitor id the impressions use. */
|
|
1122
|
+
declare const EXPERIENCE_VISITOR_CART_ATTRIBUTE = "pb_vid__";
|
|
1123
|
+
/**
|
|
1124
|
+
* The exposure list from a raw cookie value, re-encoded in the platform's wire
|
|
1125
|
+
* format (malformed and expired entries dropped), or `null` when nothing valid
|
|
1126
|
+
* is left. Pure; `now` is epoch SECONDS.
|
|
1127
|
+
*/
|
|
1128
|
+
declare function normalizeExposureList(raw: string | null | undefined, now?: number): string | null;
|
|
1129
|
+
/**
|
|
1130
|
+
* The long-lived visitor id the browser SDK records impressions under, read
|
|
1131
|
+
* from the request's cookies in the SDK's own order (`readBucketingId`):
|
|
1132
|
+
* Shopify's `_y` (the SDK reads it from Server-Timing; the server sees the
|
|
1133
|
+
* cookie itself), then a Shopify client-id cookie (`shopify_client_id`, then
|
|
1134
|
+
* the legacy `_shopify_y`), then Playbook's `_pb_visitor_id`. `null` when none
|
|
1135
|
+
* is present. Call it only with analytics consent.
|
|
1136
|
+
*
|
|
1137
|
+
* Never the session-only `_pb_session_vid`: the SDK can't read it (HttpOnly),
|
|
1138
|
+
* so no impression is ever recorded under it.
|
|
1139
|
+
*/
|
|
1140
|
+
declare function experienceVisitorIdFromCookies(cookies: Record<string, string | undefined>): string | null;
|
|
1141
|
+
type ExperienceAttributionConsent = 'allowed' | 'denied' | 'unknown';
|
|
1142
|
+
interface ExperienceAttributionInput {
|
|
1143
|
+
consent: ExperienceAttributionConsent;
|
|
1144
|
+
/** The request's `_pb_exp` cookie, raw. */
|
|
1145
|
+
exposureCookie: string | null | undefined;
|
|
1146
|
+
/** From `experienceVisitorIdFromCookies`. */
|
|
1147
|
+
visitorId: string | null | undefined;
|
|
1148
|
+
/** Epoch seconds (tests). */
|
|
1149
|
+
now?: number;
|
|
1150
|
+
}
|
|
1151
|
+
type Attr = {
|
|
1152
|
+
key: string;
|
|
1153
|
+
value?: string | null;
|
|
1154
|
+
};
|
|
1155
|
+
/**
|
|
1156
|
+
* The cart's FULL attribute list with `pb_exp__` / `pb_vid__` filled in or
|
|
1157
|
+
* removed per the policy above; `null` when the cart should be left as it is.
|
|
1158
|
+
* Every other attribute is kept, in order (a null value becomes `''`, as in
|
|
1159
|
+
* `reconcilePlaybookCartAttribute`). Pure.
|
|
1160
|
+
*/
|
|
1161
|
+
declare function reconcileExperienceCartAttributes(current: readonly Attr[] | null | undefined, { consent, exposureCookie, visitorId, now }: ExperienceAttributionInput): {
|
|
1162
|
+
key: string;
|
|
1163
|
+
value: string;
|
|
1164
|
+
}[] | null;
|
|
443
1165
|
|
|
444
1166
|
declare const CONTROL_ARM = "control";
|
|
445
1167
|
interface AssignInput {
|
|
@@ -481,4 +1203,4 @@ declare function inNamespace(hashValue: string, namespace: [string, number, numb
|
|
|
481
1203
|
declare function chooseVariation(n: number, ranges: VariationRange[]): number;
|
|
482
1204
|
declare function getBucketRanges(numVariations: number, coverage: number | undefined, weights?: number[]): VariationRange[];
|
|
483
1205
|
|
|
484
|
-
export { type AddToCartSource, type AddedLineInput, CART_VISITOR_ATTRIBUTE, CONTROL_ARM, type CartLineSnapshot, type ConsentState, type CreatePlaybookOptions, DEFAULT_EVENT_URL, DEFAULT_EXPOSURE_URL, DEFAULT_PLATFORM_URL, DEFAULT_SUPPORTED_EVENTS, LEGACY_VISITOR_COOKIE, type PlaybookArm, type PlaybookAssignReason, type PlaybookAssignment, type PlaybookDevice, PlaybookExposure, type
|
|
1206
|
+
export { AA_SITEWIDE_TEST, type AddToCartSource, type AddedLineInput, CART_SYNC_IDLE_MS, CART_VISITOR_ATTRIBUTE, CLOAK_MAX_MS, CLOAK_STYLE_ID, CONSENT_LOADED_EVENTS, CONTROL_ARM, type CartAttribute, type CartAttributeReader, type CartAttributeWriter, type CartLineSnapshot, type CartSyncEvent, type CartSyncSnapshot, type CartWriteResult, type ConsentState, type CreatePlaybookContextOptions, type CreatePlaybookOptions, DEFAULT_DATALAYER_EVENT, DEFAULT_EVENT_URL, DEFAULT_EXPERIENCE_SDK_URL, DEFAULT_EXPOSURE_URL, DEFAULT_PLATFORM_URL, DEFAULT_PROXY_ENDPOINT, DEFAULT_SDK_URL, DEFAULT_SUPPORTED_EVENTS, EXPERIENCE_SDK_SCRIPT_ID, EXPERIENCE_VISITOR_CART_ATTRIBUTE, EXPOSURE_CART_ATTRIBUTE, EXPOSURE_COOKIE, type ExperienceAttributionConsent, type ExperienceAttributionInput, type HeadSnippetParts, LEGACY_VISITOR_COOKIE, MAX_WRITES_PER_CART, PlaybookAAExposure, type PlaybookArm, type PlaybookAssignReason, type PlaybookAssignment, PlaybookBoundary, type PlaybookCartAdapter, type PlaybookClientConsent, type PlaybookCloakConfig, PlaybookCloakHead, type PlaybookConsentAdapter, type PlaybookDataLayerOption, type PlaybookDebugExplain, type PlaybookDebugOptions, PlaybookDebugPanel, type PlaybookDevice, type PlaybookEnv, PlaybookExposure, PlaybookHead, type PlaybookHeadProps, type PlaybookHeadSnippetOptions, type PlaybookLoaderData, type PlaybookPreview, PlaybookProvider, type PlaybookProxyOptions, type PlaybookRequestContext, PlaybookRoot, type PlaybookRootProps, type PlaybookRuleset, type PlaybookServerConsent, type PlaybookServerResult, type PlaybookState, type PlaybookStoreContext, type PlaybookTestRule, type PlaybookTestStatus, type PlaybookVariant, type PlaybookVisitorType, type RulesetSource, SESSION_VISITOR_COOKIE, STANDARD_EVENTS, type StandardEvent, TRUEVAULT_CONSENT_COOKIE, type TrackScope, type TrackedEntry, type TrueVaultConsentOptions, VISITOR_COOKIE, addedLinesFrom, analyticsConsentFromCookie, assignTest, buildHeadSnippet, cartHasPlaybookAttribute, chooseVariation, consentFromAnalytics, createCartAttributeReader, createCartAttributeSync, createCartAttributeWriter, createPlaybook, createPlaybookContext, createPlaybookProxyHandler, createTrueVaultConsent, debugPanelAllowed, declareConsentRequired, detectDevice, detectGeo, experienceVisitorIdFromCookies, getBucketRanges, getConsentState, getEqualWeights, getServerTrackedLog, getSessionContext, getTargetedPages, getTrackedLog, hasPlaybookParams, hasSentExposure, hash, inNamespace, isAnalyticsConsentGranted, isKillSwitchOn, isPreviewHost, manifestUrl, matchTargetedPage, matchesPathPrefix, mergeAttributes, normalizeExposureList, onConsentChange, onConsentLoaded, playbookBackendUrl, playbookCartAttribute, playbookHeadSnippet, playbookHeadSnippetHtml, playbookTrack, prefetchRuleset, reconcileExperienceCartAttributes, reconcilePlaybookCartAttribute, revealScript, sanitizeManifestPages, sanitizeRuleset, setNextAddSource, shopifyCustomerPrivacyConsent, subscribeTrackedLog, syncVisitorId, takeAddSource, targetPageKey, trackAddToCart, trackAddToCartLines, trueVaultDecision, truevaultConsent, useAnalyticsAllowed, usePageEngagement, usePlaybookConsent, usePlaybookExposure, usePlaybookInteraction, usePlaybookState, usePlaybookVariant, usePreviewParamRedirect, visitorInRunningTest, visitorSeedScript, waitForConsentAPI, withPlaybook, withPlaybookCartAttribute };
|