@heyplaybook/hydrogen 0.2.1 → 0.3.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 +172 -2
- package/dist/index.d.ts +475 -45
- package/dist/index.js +1212 -119
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -21,7 +21,173 @@ npm install @heyplaybook/hydrogen
|
|
|
21
21
|
# or: pnpm add @heyplaybook/hydrogen
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Quickstart: three touchpoints (0.3.0+)
|
|
25
|
+
|
|
26
|
+
The kit moves all of the store wiring into the package. A store adds three things, plus a
|
|
27
|
+
two-line proxy route. Set `PUBLIC_PLAYBOOK_SHOP_ID` first (see [Environment](#1-environment)).
|
|
28
|
+
|
|
29
|
+
### 1. `server.ts`: one context, finalized on the way out
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
import {createPlaybookContext} from '@heyplaybook/hydrogen';
|
|
33
|
+
|
|
34
|
+
const playbook = createPlaybookContext({request, env, waitUntil});
|
|
35
|
+
// …getLoadContext: () => ({…, playbook})
|
|
36
|
+
|
|
37
|
+
if (session.isPending) response.headers.set('Set-Cookie', await session.commit());
|
|
38
|
+
if (response.status === 404) {
|
|
39
|
+
return playbook.finalize(await storefrontRedirect({request, response, storefront}));
|
|
40
|
+
}
|
|
41
|
+
return playbook.finalize(response);
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`finalize` appends (never sets) the visitor cookies, after your session cookie, and also on
|
|
45
|
+
a 404 that `storefrontRedirect` turned into a redirect. A redirect never waits on a
|
|
46
|
+
still-running rules fetch. Prefer one call? `withPlaybook(options, async (playbook) => …)`
|
|
47
|
+
wraps the handler and finalizes whatever it returns.
|
|
48
|
+
|
|
49
|
+
### 2. Root: `<PlaybookHead>` and `<PlaybookRoot>`
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
// root loader
|
|
53
|
+
return data({...(await context.playbook.loaderData()) /* playbook, hasPlaybookParams */});
|
|
54
|
+
|
|
55
|
+
// <head>
|
|
56
|
+
<PlaybookHead
|
|
57
|
+
shopId={ENV.PUBLIC_PLAYBOOK_SHOP_ID}
|
|
58
|
+
hasPlaybookParams={hasPlaybookParams}
|
|
59
|
+
state={playbook}
|
|
60
|
+
/>
|
|
61
|
+
|
|
62
|
+
// around the app (inside your cart provider)
|
|
63
|
+
const {id, attributes, status} = useCart();
|
|
64
|
+
<PlaybookRoot
|
|
65
|
+
state={playbook}
|
|
66
|
+
location={useLocation()}
|
|
67
|
+
navigate={useNavigate()}
|
|
68
|
+
cart={{cartId: id, attributes, status}}
|
|
69
|
+
>
|
|
70
|
+
<App />
|
|
71
|
+
</PlaybookRoot>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- `PlaybookHead` renders the anti-flicker style (only with Playbook URL params), the reveal
|
|
75
|
+
hook, the visitor-id seed (UUIDs only) and the **legacy `playbook.js` loader**, which runs
|
|
76
|
+
Playbook landing experiences. Pass `nonce` if your store sets a CSP.
|
|
77
|
+
- `PlaybookRoot` renders your children untouched. Everything it adds is invisible and in its
|
|
78
|
+
own error boundary: consent, page engagement, the `_pb_vid` cart attribute, the preview
|
|
79
|
+
redirect, the `aa-sitewide` A/A sentinel, and the QA panel.
|
|
80
|
+
- `cart` is **read only**. The kit writes `_pb_vid` on its own request to your cart endpoint
|
|
81
|
+
(default `/api/cart`; `serverMerges: true` if that endpoint merges attributes itself). It
|
|
82
|
+
never changes your cart status, so it can't block an add to cart.
|
|
83
|
+
|
|
84
|
+
### 3. The add-to-cart path
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
import {trackAddToCart} from '@heyplaybook/hydrogen';
|
|
88
|
+
|
|
89
|
+
// after a successful add (no user errors)
|
|
90
|
+
trackAddToCart('pdp', {lines: formData /* or the lines array */, cart: data.cart});
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Sources: `pdp`, `quick_add`, `cart_upsell`, `cross_sell`, `other`. A shared cart hook that
|
|
94
|
+
can't know the source calls `setNextAddSource(source)` in the UI and passes `undefined`.
|
|
95
|
+
|
|
96
|
+
### Proxy route
|
|
97
|
+
|
|
98
|
+
```ts
|
|
99
|
+
// app/routes/apps.playbook.$.tsx
|
|
100
|
+
import {createPlaybookProxyHandler} from '@heyplaybook/hydrogen';
|
|
101
|
+
export const {loader, action} = createPlaybookProxyHandler();
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Reads `PLAYBOOK_PLATFORM_URL` from the load context. A slow platform gets a 504 after 5
|
|
105
|
+
seconds instead of holding your worker.
|
|
106
|
+
|
|
107
|
+
### Cart attribute at creation (recommended)
|
|
108
|
+
|
|
109
|
+
Writing `_pb_vid` after the fact can race other attribute writers (Intelligems writes when
|
|
110
|
+
the cart id first appears). Attach it when the cart is created, in your cart action:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
import {withPlaybookCartAttribute} from '@heyplaybook/hydrogen';
|
|
114
|
+
|
|
115
|
+
case 'Create':
|
|
116
|
+
result = await cart.create(withPlaybookCartAttribute(input, context.playbook.cartAttribute()));
|
|
117
|
+
case 'LinesAdd': // the first add creates the cart
|
|
118
|
+
const attr = context.playbook.cartAttribute();
|
|
119
|
+
result = attr && !cart.getCartId()
|
|
120
|
+
? await cart.create(withPlaybookCartAttribute({lines}, attr))
|
|
121
|
+
: await cart.addLines(lines);
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
`cartAttribute()` reads cookies and consent only (no rules fetch on the cart path) and is
|
|
125
|
+
`null` without analytics consent. For a cart that already exists, the client writes once,
|
|
126
|
+
only after the cart has been idle for 3 seconds, only for a visitor in a running test, at
|
|
127
|
+
most 3 times per cart, and it puts back any `_ig*` key the write lost.
|
|
128
|
+
|
|
129
|
+
### Consent adapters
|
|
130
|
+
|
|
131
|
+
Without one, consent comes from Shopify's Customer Privacy API (client) and the
|
|
132
|
+
`_tracking_consent` cookie (server). If your consent banner does **not** feed that API, pass
|
|
133
|
+
an adapter to **both** `createPlaybookContext({consent})` and `<PlaybookRoot consent>`, so
|
|
134
|
+
the server and client make the same decision:
|
|
135
|
+
|
|
136
|
+
```ts
|
|
137
|
+
import {truevaultConsent} from '@heyplaybook/hydrogen'; // TrueVault Polaris
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
`truevaultConsent` reads `polaris_consent_settings.analyticsPermitted`. With no cookie yet it
|
|
141
|
+
is `pending` (closed: nothing is tracked until the shopper's banner decision is recorded);
|
|
142
|
+
`createTrueVaultConsent({whenMissing: 'granted'})` changes that.
|
|
143
|
+
|
|
144
|
+
Global Privacy Control (`Sec-GPC: 1` / `navigator.globalPrivacyControl`) **follows the
|
|
145
|
+
banner** by default. GPC is an opt-out of sale and sharing, and Playbook doesn't sell data, so
|
|
146
|
+
GPC alone doesn't switch analytics off; the banner's `analyticsPermitted` decides (Polaris
|
|
147
|
+
handles GPC the same way). A store that wants GPC to deny analytics too passes
|
|
148
|
+
`createTrueVaultConsent({gpc: 'deny'})`.
|
|
149
|
+
Pending never writes or expires the persistent `_pb_visitor_id`; only a denial expires it.
|
|
150
|
+
|
|
151
|
+
### GA4: `view_experiment` on the dataLayer
|
|
152
|
+
|
|
153
|
+
Each exposure is also pushed to `window.dataLayer` (on by default), once per visitor per
|
|
154
|
+
test per session, under the same consent decision as the exposure, and never for a forced
|
|
155
|
+
or preview arm:
|
|
156
|
+
|
|
157
|
+
```js
|
|
158
|
+
{event: 'view_experiment', experiment_id: 'aa-sitewide', experiment_name: 'aa-sitewide',
|
|
159
|
+
variant_id: 'b', variant_name: 'b', experiment_variant: 'b', pb_vid: '<visitor id>'}
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
- `experiment_variant` matches the legacy `playbook.js` `playbook_experiment` push, so one
|
|
163
|
+
GTM variable reads both. `experiment_name` is the test key unless the test's config sets
|
|
164
|
+
`experimentName`.
|
|
165
|
+
- `<PlaybookRoot dataLayer={false}>` turns it off; `dataLayer={{eventName: '…'}}` renames it.
|
|
166
|
+
- No `window.dataLayer` → nothing happens. The kit never creates one.
|
|
167
|
+
- **Getting it into GA4 is the store's setup:** its GTM container (or Fueled / Elevar) needs a
|
|
168
|
+
trigger on `view_experiment` and a GA4 event tag that forwards these fields. **BigQuery**
|
|
169
|
+
needs the store's GA4 → BigQuery export turned on.
|
|
170
|
+
|
|
171
|
+
### Kill switch and rollback
|
|
172
|
+
|
|
173
|
+
| Setting | Effect |
|
|
174
|
+
| --- | --- |
|
|
175
|
+
| `PLAYBOOK_TESTS_DISABLED=1` | Store tests off: everyone sees control, no visitor cookies, no cart attribute, no exposures or events. `playbook.js` keeps running. |
|
|
176
|
+
| Unset `PUBLIC_PLAYBOOK_SHOP_ID` | Everything off, including `playbook.js`. |
|
|
177
|
+
|
|
178
|
+
Change the variable in the storefront's environment and redeploy (Oxygen reads env at
|
|
179
|
+
deploy). No code revert is needed.
|
|
180
|
+
|
|
181
|
+
### QA panel
|
|
182
|
+
|
|
183
|
+
`?pb_debug=1` opens the panel only on a preview host (`*.myshopify.dev`, Shopify previews,
|
|
184
|
+
localhost) or on a request with a verified `pb_preview` link. On the production domain a
|
|
185
|
+
public `?pb_debug=1` shows nothing. Pass `debug={{implementedTests: ['…']}}` to label tests
|
|
186
|
+
the storefront has no code for.
|
|
187
|
+
|
|
188
|
+
## Manual integration (the building blocks)
|
|
189
|
+
|
|
190
|
+
The kit is built from these exports; use them directly if the kit doesn't fit.
|
|
25
191
|
|
|
26
192
|
### 1. Environment
|
|
27
193
|
|
|
@@ -29,8 +195,9 @@ npm install @heyplaybook/hydrogen
|
|
|
29
195
|
| --- | --- | --- |
|
|
30
196
|
| `PUBLIC_PLAYBOOK_SHOP_ID` | Yes | Your Playbook shop ID |
|
|
31
197
|
| `PLAYBOOK_PLATFORM_URL` | No | Defaults to `https://www.heyplaybook.com`. Set it only for a non-production Playbook |
|
|
198
|
+
| `PLAYBOOK_TESTS_DISABLED` | No | `1` turns off store tests only (the kit's kill switch) |
|
|
32
199
|
|
|
33
|
-
No secrets reach the client. Without a shop ID the package is inert: everyone sees
|
|
200
|
+
The kit (`createPlaybookContext`) reads these from `env` itself. No secrets reach the client. Without a shop ID the package is inert: everyone sees
|
|
34
201
|
control and no cookies are set.
|
|
35
202
|
|
|
36
203
|
### 2. Server: resolve once per document request
|
|
@@ -150,6 +317,9 @@ banner that feeds it works with no extra code.
|
|
|
150
317
|
| Exposures and events | Sent | Not sent |
|
|
151
318
|
| `_pb_vid` cart attribute | Written | Not written |
|
|
152
319
|
|
|
320
|
+
While consent is **pending**, an existing `_pb_visitor_id` from an earlier grant is left as
|
|
321
|
+
it is (not refreshed, not expired). Only a denial expires it.
|
|
322
|
+
|
|
153
323
|
- **One visitor ID**, shared with Playbook's storefront script.
|
|
154
324
|
- **Server-set, so Safari keeps it.** Safari caps cookies written by browser scripts at 7
|
|
155
325
|
days. The server re-sends `_pb_visitor_id` once per browser session (a `_pb_vs` session
|