@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 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
- # Temporary Holding Version
1
+ # @heyplaybook/hydrogen
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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`.