@heyplaybook/hydrogen 0.3.0 → 0.7.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 +177 -17
- package/dist/index.d.ts +521 -81
- package/dist/index.js +933 -236
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -21,6 +21,14 @@ import { ReactNode, Component } from 'react';
|
|
|
21
21
|
* Client: `window`/`document` touched at CALL time only (safe to import on the
|
|
22
22
|
* server). Server: `analyticsConsentFromCookie` reads Shopify's own
|
|
23
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.
|
|
24
32
|
*/
|
|
25
33
|
type ConsentState = 'granted' | 'denied' | 'pending' | 'absent';
|
|
26
34
|
/**
|
|
@@ -34,6 +42,15 @@ declare function waitForConsentAPI(): Promise<void>;
|
|
|
34
42
|
/** Granted right now? Closed while resolving a known-present API; open if absent. */
|
|
35
43
|
declare function isAnalyticsConsentGranted(): boolean;
|
|
36
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;
|
|
37
54
|
/** Subscribe to `visitorConsentCollected` (decision read from event.detail). */
|
|
38
55
|
declare function onConsentChange(cb: (granted: boolean) => void): () => void;
|
|
39
56
|
/**
|
|
@@ -45,34 +62,50 @@ declare function onConsentChange(cb: (granted: boolean) => void): () => void;
|
|
|
45
62
|
*/
|
|
46
63
|
declare function analyticsConsentFromCookie(raw: string | undefined): ConsentState;
|
|
47
64
|
|
|
48
|
-
/**
|
|
49
|
-
|
|
50
|
-
* used on BOTH sides — the server reads it from the request (cookie + GPC
|
|
51
|
-
* header), the client from `document.cookie` + `navigator` — so the server's
|
|
52
|
-
* `serverConsent` and the client's live consent can never disagree on the same
|
|
53
|
-
* inputs (0.2.1 resolved a TrueVault store to `pending` on the server and to
|
|
54
|
-
* `absent`/open on the client).
|
|
55
|
-
*
|
|
56
|
-
* Without an adapter the package keeps 0.2.1 behaviour: Shopify's Customer
|
|
57
|
-
* Privacy API on the client and its `_tracking_consent` cookie on the server.
|
|
58
|
-
* Use an adapter when the store's CMP does NOT feed that API (TrueVault
|
|
59
|
-
* Polaris on Sand Cloud never sets `window.Shopify.customerPrivacy` or
|
|
60
|
-
* `_tracking_consent`).
|
|
61
|
-
*
|
|
62
|
-
* Pass the SAME adapter to `createPlaybookContext({consent})` and
|
|
63
|
-
* `<PlaybookRoot consent>`.
|
|
64
|
-
*/
|
|
65
|
-
|
|
66
|
-
interface PlaybookConsentAdapter {
|
|
65
|
+
/** SERVER half: the decision for one request. */
|
|
66
|
+
interface PlaybookServerConsent {
|
|
67
67
|
/** Stable name, for debug output. */
|
|
68
68
|
readonly id: string;
|
|
69
69
|
/** SERVER: the decision for this request. Never throws. */
|
|
70
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;
|
|
71
76
|
/** CLIENT: the decision right now. `window`/`document` read at call time. */
|
|
72
77
|
read(): ConsentState;
|
|
73
78
|
/** CLIENT: call `onChange` whenever the decision may have changed. */
|
|
74
79
|
subscribe(onChange: () => void): () => void;
|
|
75
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;
|
|
76
109
|
/** TrueVault Polaris's banner cookie (the one Sand Cloud's Blotout/analytics read). */
|
|
77
110
|
declare const TRUEVAULT_CONSENT_COOKIE = "polaris_consent_settings";
|
|
78
111
|
interface TrueVaultConsentOptions {
|
|
@@ -141,14 +174,14 @@ interface PlaybookRuleset {
|
|
|
141
174
|
/** Why a visitor got this arm (debug/QA; mirrors the platform core's AssignReason). */
|
|
142
175
|
type PlaybookAssignReason = 'preview'
|
|
143
176
|
/** Another test is being previewed on this request: this one serves control. */
|
|
144
|
-
| 'preview-isolated' | '
|
|
177
|
+
| 'preview-isolated' | 'winner' | 'not-running' | 'no-visitor' | 'targeting-device' | 'targeting-visitor-type' | 'namespace' | 'hash-error' | 'coverage' | 'assigned' | 'unknown-test';
|
|
145
178
|
interface PlaybookAssignment {
|
|
146
179
|
arm: string;
|
|
147
180
|
status: PlaybookTestStatus;
|
|
148
181
|
reason: PlaybookAssignReason;
|
|
149
182
|
/** True only when the visitor was bucketed into a RUNNING test. */
|
|
150
183
|
inTest: boolean;
|
|
151
|
-
/** True when the arm comes from a verified `pb_preview` token
|
|
184
|
+
/** True when the arm comes from a verified `pb_preview` token. */
|
|
152
185
|
forced: boolean;
|
|
153
186
|
config: Record<string, unknown>;
|
|
154
187
|
/** Evaluated on the client against the current route (SPA navigation). */
|
|
@@ -162,8 +195,9 @@ interface PlaybookState {
|
|
|
162
195
|
visitorType: PlaybookVisitorType;
|
|
163
196
|
device: PlaybookDevice;
|
|
164
197
|
/**
|
|
165
|
-
* Analytics consent as the server saw it (
|
|
166
|
-
* 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.
|
|
167
201
|
*/
|
|
168
202
|
serverConsent: 'granted' | 'denied' | 'pending' | 'absent';
|
|
169
203
|
/** The store declared a late-loading CMP (closed until it answers). */
|
|
@@ -200,16 +234,6 @@ interface CreatePlaybookOptions {
|
|
|
200
234
|
/** Keeps a background ruleset refresh alive after the response (Workers). */
|
|
201
235
|
waitUntil?: (p: Promise<unknown>) => void;
|
|
202
236
|
fetchImpl?: typeof fetch;
|
|
203
|
-
/**
|
|
204
|
-
* Arms to force regardless of status/targeting (QA). Forced views never
|
|
205
|
-
* expose. The CALLER decides when overrides are trusted (e.g. preview hosts
|
|
206
|
-
* only) — this module applies whatever it is given.
|
|
207
|
-
*
|
|
208
|
-
* Precedence per test: a `pb_preview` token on THIS request > an override
|
|
209
|
-
* from this request (`source: 'request'`) > a `pb_preview` carried by the
|
|
210
|
-
* session cookie > a session override > natural assignment.
|
|
211
|
-
*/
|
|
212
|
-
overrides?: PlaybookOverride[];
|
|
213
237
|
/**
|
|
214
238
|
* The store's CMP may load after first paint (headless, e.g. TrueVault
|
|
215
239
|
* Polaris): with no `_tracking_consent` cookie yet, treat consent as pending
|
|
@@ -218,15 +242,11 @@ interface CreatePlaybookOptions {
|
|
|
218
242
|
*/
|
|
219
243
|
consentRequired?: boolean;
|
|
220
244
|
/**
|
|
221
|
-
*
|
|
222
|
-
*
|
|
223
|
-
*
|
|
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.
|
|
224
248
|
*/
|
|
225
|
-
consent?:
|
|
226
|
-
}
|
|
227
|
-
interface PlaybookOverride extends PlaybookPreview {
|
|
228
|
-
/** `request`: set by this request's URL; `session`: replayed from a cookie. */
|
|
229
|
-
source?: 'request' | 'session';
|
|
249
|
+
consent?: PlaybookServerConsent;
|
|
230
250
|
}
|
|
231
251
|
interface PlaybookServerResult {
|
|
232
252
|
/** Serializable; pass to the client through loader data. */
|
|
@@ -249,7 +269,7 @@ declare function detectGeo(headers: Headers): {
|
|
|
249
269
|
region: string | null;
|
|
250
270
|
};
|
|
251
271
|
declare function detectDevice(userAgent: string | null): PlaybookDevice;
|
|
252
|
-
declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl,
|
|
272
|
+
declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetchImpl, consentRequired, consent: consentAdapter, }: CreatePlaybookOptions): Promise<PlaybookServerResult>;
|
|
253
273
|
|
|
254
274
|
/**
|
|
255
275
|
* Ruleset fetch with an in-memory (per-isolate) cache.
|
|
@@ -265,6 +285,11 @@ declare function createPlaybook({ shopId, platformUrl, request, waitUntil, fetch
|
|
|
265
285
|
* shop. Inside it no render touches the network or waits: each one gets the
|
|
266
286
|
* last good copy, or control. The first render after the window retries.
|
|
267
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.
|
|
268
293
|
*/
|
|
269
294
|
|
|
270
295
|
/**
|
|
@@ -395,11 +420,180 @@ declare function withPlaybookCartAttribute<T extends object>(input: T | null | u
|
|
|
395
420
|
}[];
|
|
396
421
|
};
|
|
397
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):
|
|
473
|
+
*
|
|
474
|
+
* {playbookHeadSnippet(data.cloak, {nonce})}
|
|
475
|
+
*
|
|
476
|
+
* Returns null when the page isn't targeted.
|
|
477
|
+
*/
|
|
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
|
+
interface SsrSnapshotNode {
|
|
483
|
+
id: string;
|
|
484
|
+
html: string;
|
|
485
|
+
css: string;
|
|
486
|
+
mt?: number;
|
|
487
|
+
mb?: number;
|
|
488
|
+
}
|
|
489
|
+
interface SsrSnapshot {
|
|
490
|
+
v: number;
|
|
491
|
+
nodes: SsrSnapshotNode[];
|
|
492
|
+
}
|
|
493
|
+
interface SsrArm {
|
|
494
|
+
id: string;
|
|
495
|
+
w: number;
|
|
496
|
+
c: 0 | 1;
|
|
497
|
+
x: string | null;
|
|
498
|
+
a: {
|
|
499
|
+
s: string;
|
|
500
|
+
p: 'before' | 'after' | 'prepend' | 'append';
|
|
501
|
+
f?: string;
|
|
502
|
+
} | null;
|
|
503
|
+
hide: string[];
|
|
504
|
+
}
|
|
505
|
+
interface SsrExperiment {
|
|
506
|
+
id: string;
|
|
507
|
+
ok: 0 | 1;
|
|
508
|
+
why?: string;
|
|
509
|
+
seed: string;
|
|
510
|
+
hv: number;
|
|
511
|
+
settled: string | null;
|
|
512
|
+
arms: SsrArm[];
|
|
513
|
+
aud?: unknown;
|
|
514
|
+
}
|
|
515
|
+
interface SsrDoc {
|
|
516
|
+
keys: Record<string, number[]>;
|
|
517
|
+
prefixes: Array<[string, number[]]>;
|
|
518
|
+
exps: SsrExperiment[];
|
|
519
|
+
}
|
|
520
|
+
interface SsrPayload {
|
|
521
|
+
doc: SsrDoc;
|
|
522
|
+
snapshots: Record<string, SsrSnapshot>;
|
|
523
|
+
}
|
|
524
|
+
declare function ssrUrl(platformUrl: string, shopDomain: string): string;
|
|
525
|
+
/** The shop's SSR doc, or null when the read isn't healthy (then: cloak only). Never throws. */
|
|
526
|
+
declare function getSsrPayload(args: {
|
|
527
|
+
platformUrl: string;
|
|
528
|
+
shopDomain: string;
|
|
529
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
530
|
+
fetchImpl?: typeof fetch;
|
|
531
|
+
}): Promise<SsrPayload | null>;
|
|
532
|
+
/**
|
|
533
|
+
* The arm index for `seed` + `id` over `weights` (coverage 1), or -1. GrowthBook
|
|
534
|
+
* v2: `fnv32a(fnv32a(seed + id) + "") % 10000 / 10000`; weights that don't sum
|
|
535
|
+
* to ~1 are replaced by equal weights. Same as the embed's `pbBucket`.
|
|
536
|
+
*/
|
|
537
|
+
declare function bucketIndex(seed: string, id: string, weights: readonly number[]): number;
|
|
538
|
+
interface SsrDecision {
|
|
539
|
+
experimentId: string;
|
|
540
|
+
armId: string;
|
|
541
|
+
experienceId: string | null;
|
|
542
|
+
/** The visitor id the roll used ('' for a prior / settled arm). */
|
|
543
|
+
idSource: 'prior' | 'settled' | 'roll';
|
|
544
|
+
arm: SsrArm;
|
|
545
|
+
snapshot: SsrSnapshot | null;
|
|
546
|
+
page: {
|
|
547
|
+
t: string;
|
|
548
|
+
h: string;
|
|
549
|
+
};
|
|
550
|
+
}
|
|
551
|
+
type SsrOutcome = {
|
|
552
|
+
decision: SsrDecision;
|
|
553
|
+
} | {
|
|
554
|
+
skip: string;
|
|
555
|
+
};
|
|
556
|
+
/**
|
|
557
|
+
* The server's arm for this page, or why it can't decide (→ cloak). Pure.
|
|
558
|
+
* `consent` = the request's analytics consent as the SDK would read it.
|
|
559
|
+
*/
|
|
560
|
+
declare function decideSsr(input: {
|
|
561
|
+
payload: SsrPayload;
|
|
562
|
+
pageKey: string;
|
|
563
|
+
cookies: Record<string, string | undefined>;
|
|
564
|
+
consent: 'allowed' | 'denied' | 'unknown';
|
|
565
|
+
/**
|
|
566
|
+
* The id to roll on when the long-lived ids can't be used: the package's own
|
|
567
|
+
* visitor id for this request (`_pb_visitor_id`, or the session-scoped
|
|
568
|
+
* `_pb_session_vid` while consent isn't granted). Stable across page loads,
|
|
569
|
+
* so a visitor without consent keeps one arm, and no new cookie is written.
|
|
570
|
+
*/
|
|
571
|
+
fallbackVisitorId?: string | null;
|
|
572
|
+
nowSec?: number;
|
|
573
|
+
}): SsrOutcome;
|
|
574
|
+
/**
|
|
575
|
+
* The host's inner HTML: a Declarative Shadow DOM tree identical in structure
|
|
576
|
+
* to the embed's `build()`, so `ssr-adopt.ts` finds and adopts it. The node
|
|
577
|
+
* markup was sanitized by the platform (ssr-doc.ts uses the import sanitizer);
|
|
578
|
+
* it is the trust boundary for this `innerHTML`, as for the embed's.
|
|
579
|
+
*/
|
|
580
|
+
declare function ssrHostInnerHtml(snapshot: SsrSnapshot, page: {
|
|
581
|
+
t: string;
|
|
582
|
+
h: string;
|
|
583
|
+
}): string;
|
|
584
|
+
/** Does this slot serve the decision's anchor? Exact selector + position match. */
|
|
585
|
+
declare function slotMatches(d: SsrDecision, slot: {
|
|
586
|
+
anchor: string;
|
|
587
|
+
position?: string;
|
|
588
|
+
}): boolean;
|
|
589
|
+
|
|
398
590
|
/** The env keys the kit reads (all optional). */
|
|
399
591
|
interface PlaybookEnv {
|
|
400
592
|
PUBLIC_PLAYBOOK_SHOP_ID?: string;
|
|
401
593
|
PLAYBOOK_PLATFORM_URL?: string;
|
|
402
594
|
PLAYBOOK_TESTS_DISABLED?: string;
|
|
595
|
+
/** 0.6.0: storefront domain for the targeting manifest (see `shopDomain`). */
|
|
596
|
+
PUBLIC_PLAYBOOK_SHOP_DOMAIN?: string;
|
|
403
597
|
}
|
|
404
598
|
interface CreatePlaybookContextOptions {
|
|
405
599
|
request: Request;
|
|
@@ -414,9 +608,50 @@ interface CreatePlaybookContextOptions {
|
|
|
414
608
|
disabled?: boolean;
|
|
415
609
|
/** See `createPlaybook({consentRequired})` (Shopify consent path only). */
|
|
416
610
|
consentRequired?: boolean;
|
|
417
|
-
/**
|
|
418
|
-
|
|
419
|
-
|
|
611
|
+
/**
|
|
612
|
+
* Server consent source: a `PlaybookServerConsent` (e.g. a store's CMS
|
|
613
|
+
* session record) or a full adapter (e.g. `truevaultConsent`, then pass the
|
|
614
|
+
* same one to the client). Default: Shopify's `_tracking_consent` cookie.
|
|
615
|
+
*/
|
|
616
|
+
consent?: PlaybookServerConsent;
|
|
617
|
+
/**
|
|
618
|
+
* 0.6.0: `reconcileCartAttributes` also puts back the EXPERIENCE-test cart
|
|
619
|
+
* attributes (`pb_exp__`, `pb_vid__`) when another script wiped them, for a
|
|
620
|
+
* visitor the browser SDK has shown an experience test. Fill-only; see
|
|
621
|
+
* `./experience-attribution`. Default `true`; `false` restores 0.5.0.
|
|
622
|
+
*/
|
|
623
|
+
experienceAttribution?: boolean;
|
|
624
|
+
/**
|
|
625
|
+
* 0.6.0: read the platform's targeting manifest in `loaderData()` so the
|
|
626
|
+
* head can cloak + early-inject on a page an all-traffic experience test
|
|
627
|
+
* targets (`loaderData().cloak`, `playbookHeadSnippet`). Default `true`.
|
|
628
|
+
*/
|
|
629
|
+
cloak?: boolean;
|
|
630
|
+
/**
|
|
631
|
+
* 0.7.0: the `<PlaybookSlot>`s this store renders (anchor selector +
|
|
632
|
+
* position, exactly as the slot props). On a page an all-traffic test
|
|
633
|
+
* targets, `loaderData()` picks the visitor's arm on the server and returns
|
|
634
|
+
* it as `ssr` when one of these slots serves the arm's anchor (or the arm is
|
|
635
|
+
* the original page); the cloak then stays off for that page. Empty/absent =
|
|
636
|
+
* no server render, the 0.6.0 cloak only.
|
|
637
|
+
*/
|
|
638
|
+
ssrSlots?: ReadonlyArray<{
|
|
639
|
+
anchor: string;
|
|
640
|
+
position?: 'before' | 'after' | 'prepend' | 'append';
|
|
641
|
+
}>;
|
|
642
|
+
/**
|
|
643
|
+
* 0.6.0: the storefront DOMAIN the targeting manifest is keyed by (its
|
|
644
|
+
* `?shop=`; the Playbook UUID doesn't work there). Overrides
|
|
645
|
+
* `env.PUBLIC_PLAYBOOK_SHOP_DOMAIN`; default the request's hostname, the
|
|
646
|
+
* same fallback `playbook.js` uses on a headless store.
|
|
647
|
+
*/
|
|
648
|
+
shopDomain?: string | null;
|
|
649
|
+
/**
|
|
650
|
+
* 0.6.0: the experience SDK's `data-pb-api-base`. Default
|
|
651
|
+
* `<request origin>/apps/playbook` (the store's app-proxy route), which is
|
|
652
|
+
* what `playbook.js` passes when it's loaded from `/apps/playbook/sdk`.
|
|
653
|
+
*/
|
|
654
|
+
apiBase?: string | null;
|
|
420
655
|
fetchImpl?: typeof fetch;
|
|
421
656
|
}
|
|
422
657
|
interface PlaybookLoaderData {
|
|
@@ -424,6 +659,22 @@ interface PlaybookLoaderData {
|
|
|
424
659
|
playbook: PlaybookState | null;
|
|
425
660
|
/** For `<PlaybookHead hasPlaybookParams>` (anti-flicker). */
|
|
426
661
|
hasPlaybookParams: boolean;
|
|
662
|
+
/**
|
|
663
|
+
* 0.6.0: this path's manifest page key (`product:<handle>`, `home:`, …)
|
|
664
|
+
* when an all-traffic experience test targets it, else null. Null on any
|
|
665
|
+
* manifest failure or timeout, on `pbk`/`_pv`/preview visits, and never
|
|
666
|
+
* set by utm params alone.
|
|
667
|
+
*/
|
|
668
|
+
targetedPage: string | null;
|
|
669
|
+
/** 0.6.0: pass to `playbookHeadSnippet(cloak, {nonce})`. Null = no cloak. */
|
|
670
|
+
cloak: PlaybookCloakConfig | null;
|
|
671
|
+
/**
|
|
672
|
+
* 0.7.0: the visitor's server-rendered arm for `<PlaybookSsrHead>` /
|
|
673
|
+
* `<PlaybookSlot>`, or null (no test here, or it falls back to the cloak).
|
|
674
|
+
*/
|
|
675
|
+
ssr: SsrDecision | null;
|
|
676
|
+
/** 0.7.0: why there's no `ssr` on a targeted page (debugging), else null. */
|
|
677
|
+
ssrSkip: string | null;
|
|
427
678
|
}
|
|
428
679
|
interface PlaybookRequestContext {
|
|
429
680
|
readonly shopId: string | null;
|
|
@@ -433,6 +684,30 @@ interface PlaybookRequestContext {
|
|
|
433
684
|
get(): Promise<PlaybookServerResult | null>;
|
|
434
685
|
loaderData(): Promise<PlaybookLoaderData>;
|
|
435
686
|
cartAttribute(): CartAttribute | null;
|
|
687
|
+
/**
|
|
688
|
+
* The visitor id this request may stamp on the cart as `_pb_vid`: analytics
|
|
689
|
+
* consent granted (or no consent system and `consentRequired` off), read
|
|
690
|
+
* from `_pb_visitor_id` then `_pb_session_vid`. Never minted; null when
|
|
691
|
+
* disabled, without consent, or without an id. No ruleset fetch.
|
|
692
|
+
*/
|
|
693
|
+
cartVisitorId(): string | null;
|
|
694
|
+
/**
|
|
695
|
+
* The cart's full attribute list with `_pb_vid` added, corrected or removed
|
|
696
|
+
* (consent withdrawn / no id), every other attribute kept; `null` when the
|
|
697
|
+
* cart is already right, or when Playbook is disabled (the cart is left
|
|
698
|
+
* untouched). Call after EVERY cart action with the cart as it now stands.
|
|
699
|
+
*
|
|
700
|
+
* 0.6.0: also fills a missing `pb_exp__` / `pb_vid__` (experience tests) for
|
|
701
|
+
* a visitor with an experience exposure, and removes them on an explicit
|
|
702
|
+
* denial. Still one list, so still at most one write.
|
|
703
|
+
*/
|
|
704
|
+
reconcileCartAttributes(current: ReadonlyArray<{
|
|
705
|
+
key: string;
|
|
706
|
+
value?: string | null;
|
|
707
|
+
}> | null | undefined): {
|
|
708
|
+
key: string;
|
|
709
|
+
value: string;
|
|
710
|
+
}[] | null;
|
|
436
711
|
/** APPEND this request's Playbook cookies to `headers`. Never throws. */
|
|
437
712
|
appendCookies(headers: Headers): Promise<void>;
|
|
438
713
|
/**
|
|
@@ -443,7 +718,7 @@ interface PlaybookRequestContext {
|
|
|
443
718
|
*/
|
|
444
719
|
finalize(response: Response): Promise<Response>;
|
|
445
720
|
}
|
|
446
|
-
declare function createPlaybookContext({ request, env, waitUntil, shopId: shopIdOption, platformUrl: platformUrlOption, disabled: disabledOption, consentRequired, consent,
|
|
721
|
+
declare function createPlaybookContext({ request, env, waitUntil, shopId: shopIdOption, platformUrl: platformUrlOption, disabled: disabledOption, consentRequired, consent, experienceAttribution, cloak: cloakOption, ssrSlots, shopDomain: shopDomainOption, apiBase: apiBaseOption, fetchImpl, }: CreatePlaybookContextOptions): PlaybookRequestContext;
|
|
447
722
|
/**
|
|
448
723
|
* Wrapper form: creates the context, runs the store's handler with it, then
|
|
449
724
|
* finalizes whatever response the handler returns (incl. a redirect built
|
|
@@ -476,6 +751,91 @@ interface PlaybookHeadProps {
|
|
|
476
751
|
}
|
|
477
752
|
declare function PlaybookHead({ shopId, apiEndpoint, sdkUrl, hasPlaybookParams, state, visitorId, nonce, }: PlaybookHeadProps): react_jsx_runtime.JSX.Element | null;
|
|
478
753
|
|
|
754
|
+
declare function manifestUrl(platformUrl: string, shopDomain: string): string;
|
|
755
|
+
/**
|
|
756
|
+
* The manifest's `pages` as clean strings, or null when the envelope is not
|
|
757
|
+
* a manifest. A manifest without `pages` (an older platform) is `[]` — valid,
|
|
758
|
+
* nothing targeted. Non-string entries are dropped.
|
|
759
|
+
*/
|
|
760
|
+
declare function sanitizeManifestPages(value: unknown): string[] | null;
|
|
761
|
+
/**
|
|
762
|
+
* The shop's all-traffic page keys, or `null` when the read is not healthy
|
|
763
|
+
* (failure, timeout, backoff, last-good during an outage) — the caller must
|
|
764
|
+
* then NOT hide. Never throws.
|
|
765
|
+
*/
|
|
766
|
+
declare function getTargetedPages({ platformUrl, shopDomain, waitUntil, fetchImpl, }: {
|
|
767
|
+
platformUrl: string;
|
|
768
|
+
shopDomain: string;
|
|
769
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
770
|
+
fetchImpl?: typeof fetch;
|
|
771
|
+
}): Promise<{
|
|
772
|
+
pages: string[] | null;
|
|
773
|
+
source: RulesetSource;
|
|
774
|
+
}>;
|
|
775
|
+
/**
|
|
776
|
+
* The manifest page key for a storefront path — a byte-for-byte port of
|
|
777
|
+
* `targetPageKey` in shared/src/targeting/index.ts (the same function the
|
|
778
|
+
* `playbook.js` loader and the experience SDK use):
|
|
779
|
+
* `product:<handle>` (also under `/collections/<c>/products/<p>`),
|
|
780
|
+
* `collection:<handle>`, `home:`, `page:<handle>` for `/pages/<handle>`,
|
|
781
|
+
* `page:cart`, `page:<path>` for any other storefront path; null for an
|
|
782
|
+
* untargetable path. A leading locale segment (`/en-us`, `/fr`) and a
|
|
783
|
+
* trailing slash are stripped; handles are URI-decoded and lowercased.
|
|
784
|
+
*/
|
|
785
|
+
declare function targetPageKey(pathname: string): string | null;
|
|
786
|
+
/**
|
|
787
|
+
* This path's page key when the manifest serves it to all traffic, else null.
|
|
788
|
+
* Same matching as `manifestMatchesPage` (shared): exact key, or a key ending
|
|
789
|
+
* in `*` by prefix (`"*"`, `"product:*"`, `"product:the-weekender-in-*"`).
|
|
790
|
+
*/
|
|
791
|
+
declare function matchTargetedPage(pages: readonly string[] | null | undefined, pathname: string): string | null;
|
|
792
|
+
|
|
793
|
+
/**
|
|
794
|
+
* `window.__pbSsr` (so the SDK adopts the arm and reports it as shown) and the
|
|
795
|
+
* arm's theme-section hides, before first paint. Renders nothing without a
|
|
796
|
+
* decision.
|
|
797
|
+
*/
|
|
798
|
+
declare function PlaybookSsrHead({ ssr, nonce }: {
|
|
799
|
+
ssr: SsrDecision | null | undefined;
|
|
800
|
+
nonce?: string;
|
|
801
|
+
}): react_jsx_runtime.JSX.Element | null;
|
|
802
|
+
/**
|
|
803
|
+
* The server-rendered arm, placed by the store where the test's anchor is.
|
|
804
|
+
* Renders only when the decision's arm targets exactly this anchor + position;
|
|
805
|
+
* otherwise nothing (and the SDK renders as usual).
|
|
806
|
+
*/
|
|
807
|
+
declare function PlaybookSlot({ ssr, anchor, position, }: {
|
|
808
|
+
ssr: SsrDecision | null | undefined;
|
|
809
|
+
/** The CSS selector the test anchors to, exactly as Playbook stores it. */
|
|
810
|
+
anchor: string;
|
|
811
|
+
position?: 'before' | 'after' | 'prepend' | 'append';
|
|
812
|
+
}): react_jsx_runtime.JSX.Element | null;
|
|
813
|
+
|
|
814
|
+
/**
|
|
815
|
+
* Store-specific "why not in test" text for the QA panel. Return a string to
|
|
816
|
+
* show it (it wins over the generic reason), or null to fall back to the
|
|
817
|
+
* generic reason. Runs in the browser; must not throw (errors are ignored).
|
|
818
|
+
*/
|
|
819
|
+
type PlaybookDebugExplain = (testKey: string, assignment: PlaybookAssignment, pathname: string) => string | null | undefined;
|
|
820
|
+
/** `<PlaybookRoot debug>` options. */
|
|
821
|
+
interface PlaybookDebugOptions {
|
|
822
|
+
/** Force allow/deny; default: preview hosts or a verified preview token. */
|
|
823
|
+
allowed?: boolean;
|
|
824
|
+
/** Test keys this storefront has code for (others are labelled as such). */
|
|
825
|
+
implementedTests?: string[];
|
|
826
|
+
/** Store-specific eligibility text (e.g. "not a towel product"). */
|
|
827
|
+
explain?: PlaybookDebugExplain;
|
|
828
|
+
}
|
|
829
|
+
/** May the panel open on this page? */
|
|
830
|
+
declare function debugPanelAllowed(state: PlaybookState | null | undefined, hostname: string, allowed?: boolean): boolean;
|
|
831
|
+
declare function PlaybookDebugPanel({ state, location, allowed, implementedTests, explain, }: {
|
|
832
|
+
state: PlaybookState | null | undefined;
|
|
833
|
+
location: {
|
|
834
|
+
pathname: string;
|
|
835
|
+
search?: string;
|
|
836
|
+
};
|
|
837
|
+
} & PlaybookDebugOptions): react_jsx_runtime.JSX.Element | null;
|
|
838
|
+
|
|
479
839
|
/**
|
|
480
840
|
* The standard events — ONE taxonomy for every store (GROWTH-TESTS.md "The
|
|
481
841
|
* standard events"). Store-specific interactions are `variant_interaction`
|
|
@@ -491,10 +851,13 @@ interface PlaybookStoreContext {
|
|
|
491
851
|
isLoggedIn?: boolean | null;
|
|
492
852
|
}
|
|
493
853
|
/**
|
|
494
|
-
* GA4 / GTM forwarding of exposures.
|
|
495
|
-
*
|
|
854
|
+
* GA4 / GTM forwarding of exposures. OFF by default since 0.5.0 (a store that
|
|
855
|
+
* also runs another testing tool's `view_experiment` — e.g. Pack tests — would
|
|
856
|
+
* get two tools' experiments mixed in GA4). `true` or `{}` turns it on;
|
|
857
|
+
* `{eventName}` turns it on under another event name (default
|
|
858
|
+
* `view_experiment`); `false` keeps it off.
|
|
496
859
|
*/
|
|
497
|
-
type PlaybookDataLayerOption =
|
|
860
|
+
type PlaybookDataLayerOption = boolean | {
|
|
498
861
|
eventName?: string;
|
|
499
862
|
};
|
|
500
863
|
declare const DEFAULT_DATALAYER_EVENT = "view_experiment";
|
|
@@ -572,8 +935,16 @@ interface PlaybookRootProps {
|
|
|
572
935
|
replace: true;
|
|
573
936
|
preventScrollReset: true;
|
|
574
937
|
}) => void;
|
|
938
|
+
/**
|
|
939
|
+
* Client `_pb_vid` sync. `null` turns it off — do that when the server owns
|
|
940
|
+
* `_pb_vid` (`context.playbook.reconcileCartAttributes` in the cart action).
|
|
941
|
+
*/
|
|
575
942
|
cart?: PlaybookCartAdapter | null;
|
|
576
|
-
|
|
943
|
+
/**
|
|
944
|
+
* Browser consent: a `PlaybookClientConsent` or a full adapter. Default:
|
|
945
|
+
* Shopify's Customer Privacy API (`shopifyCustomerPrivacyConsent`).
|
|
946
|
+
*/
|
|
947
|
+
consent?: PlaybookClientConsent;
|
|
577
948
|
storeContext?: PlaybookStoreContext;
|
|
578
949
|
/**
|
|
579
950
|
* The store's own CMS/editor preview (e.g. Pack customizer): no cart write,
|
|
@@ -582,13 +953,18 @@ interface PlaybookRootProps {
|
|
|
582
953
|
editorPreview?: boolean;
|
|
583
954
|
/** Render the `aa-sitewide` sentinel (default true; inert without that test). */
|
|
584
955
|
aaSentinel?: boolean;
|
|
585
|
-
/**
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
|
|
590
|
-
/**
|
|
956
|
+
/**
|
|
957
|
+
* QA panel: force allow/deny, the test keys this store has code for, and
|
|
958
|
+
* `explain` for store-specific "why not in test" text.
|
|
959
|
+
*/
|
|
960
|
+
debug?: PlaybookDebugOptions;
|
|
961
|
+
/**
|
|
962
|
+
* GA4 `view_experiment` dataLayer push per exposure. OFF by default since
|
|
963
|
+
* 0.5.0; `true` / `{eventName}` turns it on.
|
|
964
|
+
*/
|
|
591
965
|
dataLayer?: PlaybookDataLayerOption;
|
|
966
|
+
/** A verified preview shows its arm even off-target (default false). */
|
|
967
|
+
previewIgnoresTargeting?: boolean;
|
|
592
968
|
/** Observe cart-sync decisions (debug/logging). */
|
|
593
969
|
onCartSyncEvent?: (event: CartSyncEvent) => void;
|
|
594
970
|
exposureUrl?: string;
|
|
@@ -606,21 +982,7 @@ declare function visitorInRunningTest(state: PlaybookState | null | undefined):
|
|
|
606
982
|
declare function PlaybookAAExposure({ testKey }: {
|
|
607
983
|
testKey?: string;
|
|
608
984
|
}): react_jsx_runtime.JSX.Element;
|
|
609
|
-
declare function PlaybookRoot({ state, location, navigate, cart, consent, storeContext, editorPreview, aaSentinel, debug, dataLayer, onCartSyncEvent, exposureUrl, eventUrl, supportedEvents, children, }: PlaybookRootProps): react_jsx_runtime.JSX.Element;
|
|
610
|
-
|
|
611
|
-
/** May the panel open on this page? */
|
|
612
|
-
declare function debugPanelAllowed(state: PlaybookState | null | undefined, hostname: string, allowed?: boolean): boolean;
|
|
613
|
-
declare function PlaybookDebugPanel({ state, location, allowed, implementedTests, }: {
|
|
614
|
-
state: PlaybookState | null | undefined;
|
|
615
|
-
location: {
|
|
616
|
-
pathname: string;
|
|
617
|
-
search?: string;
|
|
618
|
-
};
|
|
619
|
-
/** Force allow/deny; default: preview hosts or a verified preview token. */
|
|
620
|
-
allowed?: boolean;
|
|
621
|
-
/** Test keys this storefront has code for (others are labelled as such). */
|
|
622
|
-
implementedTests?: string[];
|
|
623
|
-
}): react_jsx_runtime.JSX.Element | null;
|
|
985
|
+
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;
|
|
624
986
|
|
|
625
987
|
interface Props {
|
|
626
988
|
/** For the console warning only. */
|
|
@@ -700,9 +1062,10 @@ interface PlaybookVariant {
|
|
|
700
1062
|
* state, so SSR and hydration render the same arm (no flicker).
|
|
701
1063
|
*
|
|
702
1064
|
* `eligible: false` (e.g. "not a towel product") → control, not in test.
|
|
703
|
-
* A forced arm (
|
|
704
|
-
*
|
|
705
|
-
*
|
|
1065
|
+
* A forced arm (a verified `pb_preview` link) skips status and traffic split
|
|
1066
|
+
* but still respects targeting: a towel arm forced on a towel page must not
|
|
1067
|
+
* follow the session onto a bedding page. A store that wants previews to show
|
|
1068
|
+
* the arm everywhere passes `<PlaybookRoot previewIgnoresTargeting>`.
|
|
706
1069
|
*/
|
|
707
1070
|
declare function usePlaybookVariant(testKey: string, { eligible }?: {
|
|
708
1071
|
eligible?: boolean;
|
|
@@ -737,7 +1100,7 @@ declare function usePreviewParamRedirect(location: {
|
|
|
737
1100
|
hash: string;
|
|
738
1101
|
}): string | null;
|
|
739
1102
|
|
|
740
|
-
declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, consent: consentAdapter, dataLayer, children, }: {
|
|
1103
|
+
declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supportedEvents, storeContext, consent: consentAdapter, dataLayer, previewIgnoresTargeting, children, }: {
|
|
741
1104
|
state: PlaybookState | null | undefined;
|
|
742
1105
|
/** Current route pathname (re-render on navigation so path targeting updates). */
|
|
743
1106
|
pathname: string;
|
|
@@ -748,15 +1111,24 @@ declare function PlaybookProvider({ state, pathname, exposureUrl, eventUrl, supp
|
|
|
748
1111
|
/** Market / locale / login state, for the exposure context. */
|
|
749
1112
|
storeContext?: PlaybookStoreContext;
|
|
750
1113
|
/**
|
|
751
|
-
*
|
|
752
|
-
*
|
|
1114
|
+
* Browser consent source (a `PlaybookClientConsent`, or a full adapter).
|
|
1115
|
+
* Default: Shopify's Customer Privacy API (`shopifyCustomerPrivacyConsent`).
|
|
1116
|
+
* Keep it closed on the same "unknown" states as the server source.
|
|
753
1117
|
*/
|
|
754
|
-
consent?:
|
|
1118
|
+
consent?: PlaybookClientConsent;
|
|
755
1119
|
/**
|
|
756
|
-
* Forward each exposure to `window.dataLayer` as GA4 `view_experiment
|
|
757
|
-
*
|
|
1120
|
+
* Forward each exposure to `window.dataLayer` as GA4 `view_experiment`.
|
|
1121
|
+
* OFF by default since 0.5.0; `true` / `{}` turns it on, `{eventName}`
|
|
1122
|
+
* renames it.
|
|
758
1123
|
*/
|
|
759
1124
|
dataLayer?: PlaybookDataLayerOption;
|
|
1125
|
+
/**
|
|
1126
|
+
* A verified preview (`pb_preview`) shows the forced arm even where the
|
|
1127
|
+
* test doesn't apply (`eligible: false` or an off-target path). Default
|
|
1128
|
+
* false: the forced arm respects targeting, so an arm previewed on a towel
|
|
1129
|
+
* page doesn't follow the reviewer onto a bedding page.
|
|
1130
|
+
*/
|
|
1131
|
+
previewIgnoresTargeting?: boolean;
|
|
760
1132
|
children: ReactNode;
|
|
761
1133
|
}): react_jsx_runtime.JSX.Element;
|
|
762
1134
|
/** Component form of `usePlaybookExposure` for wrapping an existing element. */
|
|
@@ -870,6 +1242,74 @@ declare function cartHasPlaybookAttribute(attributes: ReadonlyArray<{
|
|
|
870
1242
|
key: string;
|
|
871
1243
|
value?: string | null;
|
|
872
1244
|
}> | null | undefined, visitorId: string): boolean;
|
|
1245
|
+
/**
|
|
1246
|
+
* The cart's FULL attribute list with `_pb_vid` reconciled to `visitorId`:
|
|
1247
|
+
* added when missing, corrected when stale (or duplicated), removed when
|
|
1248
|
+
* `visitorId` is null (no id, or consent withdrawn). Every other attribute is
|
|
1249
|
+
* kept as-is, in order. Returns `null` when the cart is already right, so the
|
|
1250
|
+
* caller skips the mutation.
|
|
1251
|
+
*
|
|
1252
|
+
* Pure: it never mints an id. Pass the result to a REPLACE-style write
|
|
1253
|
+
* (Hydrogen's `cart.updateAttributes`), which is why the whole list comes
|
|
1254
|
+
* back rather than just `_pb_vid`. A null/empty value on another key is
|
|
1255
|
+
* written back as `''`.
|
|
1256
|
+
*/
|
|
1257
|
+
declare function reconcilePlaybookCartAttribute(current: ReadonlyArray<{
|
|
1258
|
+
key: string;
|
|
1259
|
+
value?: string | null;
|
|
1260
|
+
}> | null | undefined, visitorId: string | null | undefined): {
|
|
1261
|
+
key: string;
|
|
1262
|
+
value: string;
|
|
1263
|
+
}[] | null;
|
|
1264
|
+
|
|
1265
|
+
/** The SDK's exposure-list cookie (30 days). */
|
|
1266
|
+
declare const EXPOSURE_COOKIE = "_pb_exp";
|
|
1267
|
+
/** Cart attribute the `orders/paid` webhook decodes as the exposure list. */
|
|
1268
|
+
declare const EXPOSURE_CART_ATTRIBUTE = "pb_exp__";
|
|
1269
|
+
/** Cart attribute carrying the long-lived visitor id the impressions use. */
|
|
1270
|
+
declare const EXPERIENCE_VISITOR_CART_ATTRIBUTE = "pb_vid__";
|
|
1271
|
+
/**
|
|
1272
|
+
* The exposure list from a raw cookie value, re-encoded in the platform's wire
|
|
1273
|
+
* format (malformed and expired entries dropped), or `null` when nothing valid
|
|
1274
|
+
* is left. Pure; `now` is epoch SECONDS.
|
|
1275
|
+
*/
|
|
1276
|
+
declare function normalizeExposureList(raw: string | null | undefined, now?: number): string | null;
|
|
1277
|
+
/**
|
|
1278
|
+
* The long-lived visitor id the browser SDK records impressions under, read
|
|
1279
|
+
* from the request's cookies in the SDK's own order (`readBucketingId`):
|
|
1280
|
+
* Shopify's `_y` (the SDK reads it from Server-Timing; the server sees the
|
|
1281
|
+
* cookie itself), then a Shopify client-id cookie (`shopify_client_id`, then
|
|
1282
|
+
* the legacy `_shopify_y`), then Playbook's `_pb_visitor_id`. `null` when none
|
|
1283
|
+
* is present. Call it only with analytics consent.
|
|
1284
|
+
*
|
|
1285
|
+
* Never the session-only `_pb_session_vid`: the SDK can't read it (HttpOnly),
|
|
1286
|
+
* so no impression is ever recorded under it.
|
|
1287
|
+
*/
|
|
1288
|
+
declare function experienceVisitorIdFromCookies(cookies: Record<string, string | undefined>): string | null;
|
|
1289
|
+
type ExperienceAttributionConsent = 'allowed' | 'denied' | 'unknown';
|
|
1290
|
+
interface ExperienceAttributionInput {
|
|
1291
|
+
consent: ExperienceAttributionConsent;
|
|
1292
|
+
/** The request's `_pb_exp` cookie, raw. */
|
|
1293
|
+
exposureCookie: string | null | undefined;
|
|
1294
|
+
/** From `experienceVisitorIdFromCookies`. */
|
|
1295
|
+
visitorId: string | null | undefined;
|
|
1296
|
+
/** Epoch seconds (tests). */
|
|
1297
|
+
now?: number;
|
|
1298
|
+
}
|
|
1299
|
+
type Attr = {
|
|
1300
|
+
key: string;
|
|
1301
|
+
value?: string | null;
|
|
1302
|
+
};
|
|
1303
|
+
/**
|
|
1304
|
+
* The cart's FULL attribute list with `pb_exp__` / `pb_vid__` filled in or
|
|
1305
|
+
* removed per the policy above; `null` when the cart should be left as it is.
|
|
1306
|
+
* Every other attribute is kept, in order (a null value becomes `''`, as in
|
|
1307
|
+
* `reconcilePlaybookCartAttribute`). Pure.
|
|
1308
|
+
*/
|
|
1309
|
+
declare function reconcileExperienceCartAttributes(current: readonly Attr[] | null | undefined, { consent, exposureCookie, visitorId, now }: ExperienceAttributionInput): {
|
|
1310
|
+
key: string;
|
|
1311
|
+
value: string;
|
|
1312
|
+
}[] | null;
|
|
873
1313
|
|
|
874
1314
|
declare const CONTROL_ARM = "control";
|
|
875
1315
|
interface AssignInput {
|
|
@@ -911,4 +1351,4 @@ declare function inNamespace(hashValue: string, namespace: [string, number, numb
|
|
|
911
1351
|
declare function chooseVariation(n: number, ranges: VariationRange[]): number;
|
|
912
1352
|
declare function getBucketRanges(numVariations: number, coverage: number | undefined, weights?: number[]): VariationRange[];
|
|
913
1353
|
|
|
914
|
-
export { AA_SITEWIDE_TEST, type AddToCartSource, type AddedLineInput, CART_SYNC_IDLE_MS, CART_VISITOR_ATTRIBUTE, 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_EXPOSURE_URL, DEFAULT_PLATFORM_URL, DEFAULT_PROXY_ENDPOINT, DEFAULT_SDK_URL, DEFAULT_SUPPORTED_EVENTS, LEGACY_VISITOR_COOKIE, MAX_WRITES_PER_CART, PlaybookAAExposure, type PlaybookArm, type PlaybookAssignReason, type PlaybookAssignment, PlaybookBoundary, type PlaybookCartAdapter, type PlaybookConsentAdapter, type PlaybookDataLayerOption, PlaybookDebugPanel, type PlaybookDevice, type PlaybookEnv, PlaybookExposure, PlaybookHead, type PlaybookHeadProps, type
|
|
1354
|
+
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, PlaybookSlot, PlaybookSsrHead, type PlaybookState, type PlaybookStoreContext, type PlaybookTestRule, type PlaybookTestStatus, type PlaybookVariant, type PlaybookVisitorType, type RulesetSource, SESSION_VISITOR_COOKIE, STANDARD_EVENTS, type SsrDecision, type SsrOutcome, type SsrPayload, type StandardEvent, TRUEVAULT_CONSENT_COOKIE, type TrackScope, type TrackedEntry, type TrueVaultConsentOptions, VISITOR_COOKIE, addedLinesFrom, analyticsConsentFromCookie, assignTest, bucketIndex, buildHeadSnippet, cartHasPlaybookAttribute, chooseVariation, consentFromAnalytics, createCartAttributeReader, createCartAttributeSync, createCartAttributeWriter, createPlaybook, createPlaybookContext, createPlaybookProxyHandler, createTrueVaultConsent, debugPanelAllowed, decideSsr, declareConsentRequired, detectDevice, detectGeo, experienceVisitorIdFromCookies, getBucketRanges, getConsentState, getEqualWeights, getServerTrackedLog, getSessionContext, getSsrPayload, 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, slotMatches, ssrHostInnerHtml, ssrUrl, subscribeTrackedLog, syncVisitorId, takeAddSource, targetPageKey, trackAddToCart, trackAddToCartLines, trueVaultDecision, truevaultConsent, useAnalyticsAllowed, usePageEngagement, usePlaybookConsent, usePlaybookExposure, usePlaybookInteraction, usePlaybookState, usePlaybookVariant, usePreviewParamRedirect, visitorInRunningTest, visitorSeedScript, waitForConsentAPI, withPlaybook, withPlaybookCartAttribute };
|