@heyplaybook/hydrogen 0.0.0-stage → 0.1.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/LICENSE +49 -0
- package/README.md +185 -2
- package/dist/index.d.ts +474 -0
- package/dist/index.js +1320 -0
- package/package.json +56 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Pack Digital Inc.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---------------------------------------------------------------------------
|
|
24
|
+
|
|
25
|
+
src/growthbook.ts is ported from GrowthBook's JavaScript SDK
|
|
26
|
+
(https://github.com/growthbook/growthbook, packages/sdk-js/src/util.ts),
|
|
27
|
+
used under the following license:
|
|
28
|
+
|
|
29
|
+
MIT License
|
|
30
|
+
|
|
31
|
+
Copyright (c) 2021 GrowthBook, Inc.
|
|
32
|
+
|
|
33
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
34
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
35
|
+
in the Software without restriction, including without limitation the rights
|
|
36
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
37
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
38
|
+
furnished to do so, subject to the following conditions:
|
|
39
|
+
|
|
40
|
+
The above copyright notice and this permission notice shall be included in all
|
|
41
|
+
copies or substantial portions of the Software.
|
|
42
|
+
|
|
43
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
44
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
45
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
46
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
47
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
48
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
49
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,186 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @heyplaybook/hydrogen
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Playbook store-edit tests for Shopify Hydrogen storefronts.
|
|
4
|
+
|
|
5
|
+
Tests are defined and read out in Playbook. The variants are written in your storefront's
|
|
6
|
+
own code. This package decides which arm each visitor sees (on the server, so the first
|
|
7
|
+
paint is already right), sets a consent-aware visitor cookie, records an exposure when the
|
|
8
|
+
tested element scrolls into view, and tags the cart so orders join the test.
|
|
9
|
+
|
|
10
|
+
- React is the only peer dependency.
|
|
11
|
+
- Web-standard `Request`, `Headers` and `fetch` on the server: runs on Oxygen, Node or any
|
|
12
|
+
worker runtime.
|
|
13
|
+
- Assignment is GrowthBook's model (hash v2, namespaces, bucket ranges), ported under MIT
|
|
14
|
+
and tested against GrowthBook's published vectors. It matches Playbook's platform core
|
|
15
|
+
exactly, so readouts re-derive the same arms.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install @heyplaybook/hydrogen
|
|
21
|
+
# or: pnpm add @heyplaybook/hydrogen
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Integrate (six steps)
|
|
25
|
+
|
|
26
|
+
### 1. Environment
|
|
27
|
+
|
|
28
|
+
| Variable | Required | What |
|
|
29
|
+
| --- | --- | --- |
|
|
30
|
+
| `PUBLIC_PLAYBOOK_SHOP_ID` | Yes | Your Playbook shop ID |
|
|
31
|
+
| `PLAYBOOK_PLATFORM_URL` | No | Defaults to `https://www.heyplaybook.com`. Set it only for a non-production Playbook |
|
|
32
|
+
|
|
33
|
+
No secrets reach the client. Without a shop ID the package is inert: everyone sees
|
|
34
|
+
control and no cookies are set.
|
|
35
|
+
|
|
36
|
+
### 2. Server: resolve once per document request
|
|
37
|
+
|
|
38
|
+
In your root loader (or a request context created in `server.ts`):
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
import {createPlaybook} from '@heyplaybook/hydrogen';
|
|
42
|
+
|
|
43
|
+
const playbook = await createPlaybook({
|
|
44
|
+
shopId: env.PUBLIC_PLAYBOOK_SHOP_ID,
|
|
45
|
+
platformUrl: env.PLAYBOOK_PLATFORM_URL,
|
|
46
|
+
request,
|
|
47
|
+
waitUntil, // keeps the background ruleset refresh alive on Oxygen
|
|
48
|
+
consentRequired: true, // set when your consent banner loads after first paint
|
|
49
|
+
});
|
|
50
|
+
|
|
51
|
+
// Put the state in loader data …
|
|
52
|
+
return {playbook: playbook.state /* , … */};
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Then **append** every cookie to the document response. Use `append`, never `set`, so your
|
|
56
|
+
session and cart cookies survive:
|
|
57
|
+
|
|
58
|
+
```ts
|
|
59
|
+
for (const cookie of playbook.setCookieHeaders) {
|
|
60
|
+
response.headers.append('Set-Cookie', cookie);
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
`createPlaybook` waits at most 300 ms for the test rules (1.5 s on a cold start), then
|
|
65
|
+
uses the last good copy, or control for everyone. Rules are cached for 60 seconds. To
|
|
66
|
+
start the rules fetch earlier, call `prefetchRuleset({platformUrl, shopId, waitUntil})`
|
|
67
|
+
at the top of your request handler.
|
|
68
|
+
|
|
69
|
+
### 3. Provider
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
import {PlaybookProvider} from '@heyplaybook/hydrogen';
|
|
73
|
+
|
|
74
|
+
<PlaybookProvider state={rootData.playbook} pathname={location.pathname}>
|
|
75
|
+
<App />
|
|
76
|
+
</PlaybookProvider>
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Pass the current `pathname` so path targeting stays correct on client-side navigation.
|
|
80
|
+
|
|
81
|
+
### 4. Variants and exposure
|
|
82
|
+
|
|
83
|
+
```tsx
|
|
84
|
+
import {usePlaybookExposure, usePlaybookVariant} from '@heyplaybook/hydrogen';
|
|
85
|
+
|
|
86
|
+
function Price({price}: {price: string}) {
|
|
87
|
+
const variant = usePlaybookVariant('pdp-price-after-code');
|
|
88
|
+
const exposureRef = usePlaybookExposure('pdp-price-after-code', variant);
|
|
89
|
+
|
|
90
|
+
// Attach the ref to an element that renders in BOTH arms.
|
|
91
|
+
return (
|
|
92
|
+
<div ref={exposureRef}>
|
|
93
|
+
<p>{price}</p>
|
|
94
|
+
{variant.arm === 'b' && <PriceAfterCode />}
|
|
95
|
+
</div>
|
|
96
|
+
);
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- Control must render exactly today's UI.
|
|
101
|
+
- An exposure is sent once per visitor per test per session, only when the element is on
|
|
102
|
+
screen, only for visitors actually in the test, and never for forced or preview views.
|
|
103
|
+
- `usePlaybookVariant(key, {eligible})` lets you keep a test off pages it doesn't apply to
|
|
104
|
+
(for example, the wrong product type). A forced arm respects `eligible` too.
|
|
105
|
+
- `usePlaybookInteraction(key, variant)` returns a function for test-specific events
|
|
106
|
+
(`track('code_copied')`).
|
|
107
|
+
|
|
108
|
+
### 5. Proxy route: `/apps/playbook/*`
|
|
109
|
+
|
|
110
|
+
Exposures and events POST to `/apps/playbook/api/storefront/tests/…` on your own domain,
|
|
111
|
+
so they stay first-party. Add a route that forwards `/apps/playbook/<path>` to
|
|
112
|
+
`{PLAYBOOK_PLATFORM_URL}/<path>`:
|
|
113
|
+
|
|
114
|
+
- forward the method, body, `content-type`, `user-agent`, `referer` and `x-forwarded-for`;
|
|
115
|
+
- set `x-forwarded-host` to your host;
|
|
116
|
+
- return 204 responses with no body.
|
|
117
|
+
|
|
118
|
+
In Hydrogen (React Router) this is a splat route such as `app/routes/apps.playbook.$.tsx`
|
|
119
|
+
with a `loader` and an `action` that both proxy. To post somewhere else, pass
|
|
120
|
+
`exposureUrl` and `eventUrl` to `PlaybookProvider`.
|
|
121
|
+
|
|
122
|
+
### 6. Orders
|
|
123
|
+
|
|
124
|
+
When a cart exists, write the visitor ID as a cart attribute through your store's own
|
|
125
|
+
attribute-merge path, so other attributes survive:
|
|
126
|
+
|
|
127
|
+
```ts
|
|
128
|
+
import {cartHasPlaybookAttribute, playbookCartAttribute} from '@heyplaybook/hydrogen';
|
|
129
|
+
|
|
130
|
+
if (visitorId && !cartHasPlaybookAttribute(cart.attributes, visitorId)) {
|
|
131
|
+
await mergeCartAttributes([playbookCartAttribute(visitorId)]); // {key: '_pb_vid', value}
|
|
132
|
+
}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Re-check after cart updates: other scripts can replace the whole attribute list. Playbook's
|
|
136
|
+
`orders/paid` webhook reads `_pb_vid` from the order's note attributes.
|
|
137
|
+
|
|
138
|
+
## Consent and identity
|
|
139
|
+
|
|
140
|
+
Consent comes from Shopify's Customer Privacy API (`analytics` purpose). Any consent
|
|
141
|
+
banner that feeds it works with no extra code.
|
|
142
|
+
|
|
143
|
+
| | Consent granted, or no consent system | Consent denied or still pending |
|
|
144
|
+
| --- | --- | --- |
|
|
145
|
+
| Variant renders | Yes | Yes (rendering is functional, never gated) |
|
|
146
|
+
| Visitor cookie | `_pb_visitor_id`, 365 days, set by the server | `_pb_session_vid`, session only, HttpOnly |
|
|
147
|
+
| Exposures and events | Sent | Not sent |
|
|
148
|
+
| `_pb_vid` cart attribute | Written | Not written |
|
|
149
|
+
|
|
150
|
+
- **One visitor ID**, shared with Playbook's storefront script.
|
|
151
|
+
- **Server-set, so Safari keeps it.** Safari caps cookies written by browser scripts at 7
|
|
152
|
+
days. The server re-sends `_pb_visitor_id` once per browser session (a `_pb_vs` session
|
|
153
|
+
marker), so a cookie the browser promoted after a consent grant becomes server-set.
|
|
154
|
+
- **A grant mid-visit** promotes the session ID to the persistent cookie, keeping the same
|
|
155
|
+
arm.
|
|
156
|
+
- **Consent banners that load after first paint:** pass `consentRequired: true`, so a
|
|
157
|
+
first visit with no `_tracking_consent` cookie is treated as pending (closed) instead of
|
|
158
|
+
absent (open).
|
|
159
|
+
|
|
160
|
+
## Previews and QA
|
|
161
|
+
|
|
162
|
+
- `?pb_preview=<token>`: a signed preview link from Playbook. The package verifies it with
|
|
163
|
+
the platform, forces that arm, and keeps it in an HttpOnly session cookie
|
|
164
|
+
(`SameSite=None; Secure`, because Playbook frames the store cross-site).
|
|
165
|
+
`?pb_preview=off` clears it.
|
|
166
|
+
- `createPlaybook({overrides})`: force arms for QA from your own code, for example on
|
|
167
|
+
preview hosts only. Forced arms ignore status and traffic split, still respect page
|
|
168
|
+
targeting, and never send exposures.
|
|
169
|
+
- `usePreviewParamRedirect(location)` returns the URL that re-adds the preview param after
|
|
170
|
+
an in-app navigation, for frames where third-party cookies are blocked.
|
|
171
|
+
- Preview requests must not send `X-Frame-Options` or a `frame-ancestors` policy that
|
|
172
|
+
excludes the Playbook app.
|
|
173
|
+
|
|
174
|
+
## Behaviour
|
|
175
|
+
|
|
176
|
+
- Only `running` tests send exposures. A `completed` test with a `winner` serves the winner
|
|
177
|
+
to every eligible visitor with no exposure. `paused` serves control.
|
|
178
|
+
- A `pb_new` session cookie (no identifier) keeps a first-time visitor `new` for their
|
|
179
|
+
whole first session.
|
|
180
|
+
- Path targeting is evaluated against the current route on the client, ignoring a leading
|
|
181
|
+
locale segment (`/en-ca/products/…`).
|
|
182
|
+
|
|
183
|
+
## License
|
|
184
|
+
|
|
185
|
+
MIT. `src/growthbook.ts` is ported from GrowthBook's JavaScript SDK (MIT, © GrowthBook,
|
|
186
|
+
Inc.); see `LICENSE`.
|