@decocms/blocks 8.18.1 → 8.20.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/dist/v8/analytics/client.d.ts +10 -0
- package/dist/v8/analytics/client.d.ts.map +1 -1
- package/dist/v8/analytics/client.js +29 -3
- package/dist/v8/analytics/client.js.map +1 -1
- package/dist/v8/client.js +1 -11
- package/dist/v8/client.js.map +1 -1
- package/dist/v8/experiments.d.ts +20 -50
- package/dist/v8/experiments.d.ts.map +1 -1
- package/dist/v8/experiments.js +35 -189
- package/dist/v8/experiments.js.map +1 -1
- package/package.json +1 -1
- package/skills/deco-go-live/SKILL.md +1 -1
- package/skills/deco-go-live/references/qa-checklist-template.md +1 -1
- package/skills/deco-go-live/scripts/preflight.sh +2 -2
- package/skills/deco-nextjs-site/SKILL.md +1 -1
- package/skills/deco-nextjs-site/references/proxy-and-drafts.md +1 -1
- package/skills/deco-storefront-caching/references/perf-guardrails-e2e.md +1 -1
- package/skills/deco-storefront-caching/references/verification.md +1 -1
- package/skills/deco-storefront-caching/references/worker-page-cache.md +1 -1
- package/skills/deco-tanstack-site/references/worker-entry.md +1 -1
- package/skills/deco-v7-to-v8-migration/references/nextjs.md +1 -1
- package/skills/deco-v7-to-v8-migration/scripts/experiments.ts +1 -1
- package/skills/deco-v7-to-v8-migration/scripts/matchers.ts +5 -6
- package/skills/deco-variants/SKILL.md +3 -3
- package/skills/deco-variants/references/caching-variants.md +2 -5
- package/skills/deco-variants/references/experiments-and-campaigns.md +3 -3
- package/skills/deco-variants/references/multivariate.md +1 -1
- package/skills/deco-variants/references/v7-matchers.md +5 -17
- package/src/v8/analytics/client.ts +36 -1
- package/src/v8/client.ts +1 -12
- package/src/v8/experiments.ts +39 -209
|
@@ -169,8 +169,8 @@ if [ -n "$CAND" ]; then
|
|
|
169
169
|
|
|
170
170
|
# the first-visit visitor cookie, the split cookie and Cloudflare's own are expected
|
|
171
171
|
h=$(cc -o /dev/null -D - "$CAND/" | tr -d '\r')
|
|
172
|
-
sc=$(echo "$h" | grep -i '^set-cookie:' | grep -viE '^set-cookie: *(
|
|
173
|
-
[ -z "$sc" ] && pass "anonymous / sets no cookie besides
|
|
172
|
+
sc=$(echo "$h" | grep -i '^set-cookie:' | grep -viE '^set-cookie: *(deco_vid|_deco_bucket|__cf_bm|_cfuvid|cf_clearance)=')
|
|
173
|
+
[ -z "$sc" ] && pass "anonymous / sets no cookie besides deco_vid" ||
|
|
174
174
|
{ warn "anonymous / sets other cookies: a page cache must not store it"; echo "$sc" | cut -c1-90 | show; }
|
|
175
175
|
echo "$h" | grep -qi '^x-robots-tag:.*noindex' && fail "/ sends X-Robots-Tag noindex" || pass "/ has no X-Robots-Tag noindex"
|
|
176
176
|
xc=$(cc -o /dev/null -D - "$CAND/" | tr -d '\r' | grep -iE '^(x-cache|cf-cache-status):' | tr '\n' ' ')
|
|
@@ -31,7 +31,7 @@ example disagree, the example wins.
|
|
|
31
31
|
## The shape of a request
|
|
32
32
|
|
|
33
33
|
1. `proxy.ts` decides once: the version (a Studio link's draft or old
|
|
34
|
-
release, on an allowed host), the visitor (`
|
|
34
|
+
release, on an allowed host), the visitor (`deco_vid` cookie) and every
|
|
35
35
|
test and campaign on or off.
|
|
36
36
|
2. A published CMS page is rewritten to `/_assignments/<segment>/<path>`. The
|
|
37
37
|
page reads no request, so Next caches it (ISR).
|
|
@@ -10,7 +10,7 @@ fresh.
|
|
|
10
10
|
| Step | Function (`@decocms/nextjs/proxy`) | Result |
|
|
11
11
|
|---|---|---|
|
|
12
12
|
| Version | `decideDraft(proxyCms, request)` | A Studio link's draft or old release on an allowed host, its preview moment (`__at`) and switched tests and campaigns (`__test`, `__campaign`), the cookie to set |
|
|
13
|
-
| Visitor | `decideVisitor(request, draft)` | The `
|
|
13
|
+
| Visitor | `decideVisitor(request, draft)` | The `deco_vid` cookie, or a new visitor. Its cookie is sent on a first visit only, never when the request renders a draft or an old release |
|
|
14
14
|
| Tests and campaigns | `decideAssignments(proxyCms, draft, visitor)` | Each test of the saved `experiments` block on or off, each campaign of the saved `campaigns` block running or not. Missing blocks give none, never an error |
|
|
15
15
|
|
|
16
16
|
It forwards them to the page on request headers, always removing copies sent
|
|
@@ -37,7 +37,7 @@ the spec follows a TTL change instead of failing on it.
|
|
|
37
37
|
| Returning visitor | A cart or checkout cookie alone does not make the page private |
|
|
38
38
|
| Tracking params | `utm_*`, `gclid`, `fbclid`: 200, no `location`, same `x-cache-segment`, HIT once warm |
|
|
39
39
|
| No poisoning | A value sent in `gclid` never appears in the clean URL's HTML |
|
|
40
|
-
| No cookies on cached pages | A public page answers no `set-cookie` except `
|
|
40
|
+
| No cookies on cached pages | A public page answers no `set-cookie` except `deco_vid` on a first visit |
|
|
41
41
|
| Payload | Raw HTML under a budget; a marker of heavy data (a schema.org type you trim) under a count |
|
|
42
42
|
| Assets | A fingerprinted asset is `public, max-age=31536000, immutable` |
|
|
43
43
|
| CLS | Home and a listing under 0.1 on desktop and mobile |
|
|
@@ -27,7 +27,7 @@ done
|
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
Expect on the second request: `x-cache: HIT`, the profile you meant, `x-cache-version:
|
|
30
|
-
<build>.<revision>`, `vary: Accept-Encoding`, no `set-cookie` other than `
|
|
30
|
+
<build>.<revision>`, `vary: Accept-Encoding`, no `set-cookie` other than `deco_vid` on a first
|
|
31
31
|
visit (and the cookies in your `SAFE_COOKIES`, if a render set one). A `BYPASS` comes with `x-cache-reason`; `egress-traps.md` maps each reason to a cause.
|
|
32
32
|
|
|
33
33
|
After a deploy or a publish, `x-cache-version` changes and the first request is a `MISS` again.
|
|
@@ -41,7 +41,7 @@ You do not write these. Do not add a second copy of them in `pageCache`.
|
|
|
41
41
|
| Previews | Always render. Answer `Cache-Control: max-age=0, no-cache, must-revalidate`, `Vary: Cookie`, `noindex`, and `CDN-Cache-Control: no-store`. |
|
|
42
42
|
| `Authorization` | The page renders and answers `private, no-cache, no-store, must-revalidate`, whatever the app set. |
|
|
43
43
|
| Default CDN header | Any response without `CDN-Cache-Control` leaves with `CDN-Cache-Control: no-store`. |
|
|
44
|
-
| Visitor cookie | `
|
|
44
|
+
| Visitor cookie | `deco_vid` is set on a first visit only, and appended after `pageCache` answers. A stored copy never carries it; a visitor served from the cache still gets theirs. |
|
|
45
45
|
| `Set-Cookie` | One header per cookie (name + Domain + Path). |
|
|
46
46
|
| Fingerprinted assets | `public, max-age=31536000, immutable`, `Vary: Accept-Encoding`. Also under `/fonts/`. |
|
|
47
47
|
| CMS redirects | Answered before your `routes` and before `pageCache`. See `egress-traps.md`. |
|
|
@@ -38,7 +38,7 @@ No option turns these off.
|
|
|
38
38
|
release.
|
|
39
39
|
- **The CMS redirects**, for `GET`/`HEAD` page requests, before anything else. Server-function
|
|
40
40
|
calls, assets and `/_build` are not redirected.
|
|
41
|
-
- **The visitor and the tests.** It reads the visitor (`
|
|
41
|
+
- **The visitor and the tests.** It reads the visitor (`deco_vid` cookie, or a new one) and
|
|
42
42
|
decides each test and campaign once, then hands them to the app on request headers it strips
|
|
43
43
|
from incoming requests (below). The visitor cookie goes out on a first visit only, and never on a request that renders a draft
|
|
44
44
|
or an old release.
|
|
@@ -4,7 +4,7 @@ From the site migrations; the sites and what the commit hashes refer to are list
|
|
|
4
4
|
|
|
5
5
|
- **`transpilePackages: ['@decocms/blocks']`** only while the installed package's `exports` point at `.ts` source (see `manual-steps.md`, step 1); `8.1.0` ships `dist/` and needs none. A linked local checkout ships `dist/` and hides the difference; so does every parity run made against it.
|
|
6
6
|
- **Drafts on Pages Router SSG pages** (no proxy available, as on FastStore; `@decocms/nextjs` is for the App Router): Next 16's compiled pages runtimes inline `tryGetPreviewData`, so a `require.cache` patch never runs. See `faststore.md`.
|
|
7
|
-
- **Drafts come from `@decocms/nextjs`.** Don't hand-write the draft proxy, the draft route or the Studio bridge. In `proxy.ts`: 404 direct hits on the internal route (`isDraftRoutePath`), `decideDraft(proxyCms, request)`, then `decideVisitor(request, draft)` and `decideAssignments(proxyCms, draft, visitor)`, then `rewriteToDraftRoute(request, draft, visitor, assignments)` or `NextResponse.next({ request: { headers: assignmentsRequestHeaders(visitorRequestHeaders(draftRequestHeaders(request, draft), visitor), assignments) } })`, and `applyVisitor(applyDraft(response, draft), visitor)` for the cookies and the preview headers (`max-age=0, no-cache, must-revalidate`, noindex) (`@decocms/nextjs/proxy`). The visitor (the `
|
|
7
|
+
- **Drafts come from `@decocms/nextjs`.** Don't hand-write the draft proxy, the draft route or the Studio bridge. In `proxy.ts`: 404 direct hits on the internal route (`isDraftRoutePath`), `decideDraft(proxyCms, request)`, then `decideVisitor(request, draft)` and `decideAssignments(proxyCms, draft, visitor)`, then `rewriteToDraftRoute(request, draft, visitor, assignments)` or `NextResponse.next({ request: { headers: assignmentsRequestHeaders(visitorRequestHeaders(draftRequestHeaders(request, draft), visitor), assignments) } })`, and `applyVisitor(applyDraft(response, draft), visitor)` for the cookies and the preview headers (`max-age=0, no-cache, must-revalidate`, noindex) (`@decocms/nextjs/proxy`). The visitor (the `deco_vid` cookie, holding only its id) is what the saved `experiments` block decides A/B tests for; the proxy decides each test and campaign once (`decideAssignments`, forwarded with `assignmentsRequestHeaders`), `bindDraft` binds what it decided and `contentClient` builds `cms.client({ version, experiments, campaigns })` (`draftProxy` does all of it). On the dynamic `src/app/%5Fdraft/[[...path]]` route and in a layout that reads content: `bindDraft(cms, { searchParams })` and `contentClient(cms)` (`@decocms/nextjs/server`), with `<DraftPreviewIndicator />` on the page. A cached page can't read a request, which is why drafted requests go to that dynamic route; published CMS pages are ISR with `export const revalidate = 600` (Next renders a stored page again in the background on the first request after it is 10 minutes old, so a cached page is about that stale, which is accepted), never `force-static`, on the assignments route where the proxy decides the tests and campaigns and the page renders that (`await assignedClient(cms, segment)`). The package's README has the files in full.
|
|
8
8
|
- **Same CMS options in the proxy and the pages.** Keep `createCMS`'s options in one module both handles import (`cmsConfig`, with `site`): the proxy decides on the hosts Studio writes into the release metadata, and `bindDraft` checks again against the same ones.
|
|
9
9
|
- **Keep the block map out of the proxy.** The proxy only touches the CMS for a request with `?__draft=` or the draft cookie, but it is bundled whole. Give it its own `createCMS` handle with `blocks: {}` and the same options as the app's (one shared options module, since a second call with other options keeps the first): the draft check reads only the `CMS` settings block, so the block map, its section loaders and what they import (a GraphQL engine) leave the proxy bundle. Measured on one store: 2.2 MB to 1.5 MB, traced files 3,245 to 364. The content module still lands there.
|
|
10
10
|
- **`next start -H 127.0.0.1`** makes Next treat the draft rewrite as an external URL, and the request comes back through the proxy. Bind the default host in local checks; production hostnames aren't affected.
|
|
@@ -53,7 +53,7 @@ export function reportTestsAndDates(root: string, report: Report): void {
|
|
|
53
53
|
report.manual.push({
|
|
54
54
|
step: "content",
|
|
55
55
|
subject: "A/B tests",
|
|
56
|
-
message: `v7's random matchers (in ${quoted([...tests].map((n) => files[n] ?? n))}) weren't moved: put each test in the saved block experiments (type split-traffic) under its saved-block name, so visitors
|
|
56
|
+
message: `v7's random matchers (in ${quoted([...tests].map((n) => files[n] ?? n))}) weren't moved: put each test in the saved block experiments (type split-traffic) under its saved-block name, so its results carry over (visitors are drawn again: v8 neither reads nor writes v7's deco_segment cookie, and @decocms/compat-v7 has no random matcher), and point its rules at { "__resolveType": "experiment", "name": … } (Run an A/B test, ${RUN_AN_AB_TEST})`,
|
|
57
57
|
});
|
|
58
58
|
reportAssignment(root, report);
|
|
59
59
|
}
|
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* v7's website matchers in the block map. `@decocms/compat-v7/matchers` has
|
|
3
3
|
* each one with v7's results, taking the request explicitly; the binding's
|
|
4
|
-
* compat subpath gives that request (`matcherContext()
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
* the
|
|
8
|
-
*
|
|
9
|
-
* `campaigns` (the content step reports both, ./experiments.ts).
|
|
4
|
+
* compat subpath gives that request (`matcherContext()`). The block map
|
|
5
|
+
* registers each matcher the content uses under its v7 name. v7's random
|
|
6
|
+
* matcher isn't one of them (compat-v7 has none): its tests move by hand into
|
|
7
|
+
* the saved block `experiments`, read by the `experiment` rule, as do date
|
|
8
|
+
* windows into `campaigns` (the content step reports both, ./experiments.ts).
|
|
10
9
|
*/
|
|
11
10
|
import type { Framework } from "./framework";
|
|
12
11
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: deco-variants
|
|
3
|
-
description: "Variants on @decocms/blocks 8: the built-in multivariate block ({ rule, value } with lazy values, first true rule wins, later rules never run), the built-in rules always, never, experiment and campaign, A/B tests as the saved block experiments (split-traffic: a percentage per test, a sticky visitor id in the
|
|
3
|
+
description: "Variants on @decocms/blocks 8: the built-in multivariate block ({ rule, value } with lazy values, first true rule wins, later rules never run), the built-in rules always, never, experiment and campaign, A/B tests as the saved block experiments (split-traffic: a percentage per test, a sticky visitor id in the deco_vid cookie, @decocms/blocks/experiments) and scheduled content as the saved block campaigns (calendar), v7's matchers from @decocms/compat-v7/matchers (device, cookie, host, pathname, queryString, location, multi; v7's random moves to experiments), custom rules in the block map, previewing a variant, a test or a moment from a Studio draft link (__variant, __test, __campaign, __at), and keeping variant pages cacheable (assignmentsKey, one cache entry per set of assignments). Load it for A/B tests, scheduled or segmented content, a variant that never shows or always shows, matcher bugs after a v7 migration, or a variant page that misses the cache."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Variants on @decocms/blocks 8
|
|
@@ -17,7 +17,7 @@ Code is in `packages/blocks/src/v8/builtins/` (`multivariate.ts`, `matchers.ts`,
|
|
|
17
17
|
|---|---|
|
|
18
18
|
| [`references/multivariate.md`](./references/multivariate.md) | Writing or reading variant JSON; a variant never shows, always shows, or a slot is empty; `deco check` says "a variant's value must be a lazy block"; v7 `website/flags/multivariate*.ts` content |
|
|
19
19
|
| [`references/experiments-and-campaigns.md`](./references/experiments-and-campaigns.md) | Setting up an A/B test or a scheduled promotion; ramping a test; a campaign that never starts; `deco check` says "no test" or "no campaign"; tagging analytics with the test arm |
|
|
20
|
-
| [`references/v7-matchers.md`](./references/v7-matchers.md) | Content migrated from v7 uses `website/matchers/device.ts`, `cookie.ts`, `location.ts`, `random.ts` and others; `UNKNOWN_BLOCK` on a v7 matcher; wiring `matcherContext
|
|
20
|
+
| [`references/v7-matchers.md`](./references/v7-matchers.md) | Content migrated from v7 uses `website/matchers/device.ts`, `cookie.ts`, `location.ts`, `random.ts` and others; `UNKNOWN_BLOCK` on a v7 matcher; wiring `matcherContext`; moving a v7 random test to `experiments` |
|
|
21
21
|
| [`references/custom-matchers.md`](./references/custom-matchers.md) | Writing a site's own rule; a rule that needs the request, the visitor or the date; a rule that does not appear in Studio's rule picker |
|
|
22
22
|
| [`references/draft-preview.md`](./references/draft-preview.md) | Previewing one variant, a test switched on, or a future date from a Studio link; a preview link that shows the saved content instead |
|
|
23
23
|
| [`references/caching-variants.md`](./references/caching-variants.md) | A page with variants misses the cache or shows the wrong variant from cache; deciding whether a rule is safe behind a page cache; purging variant pages |
|
|
@@ -43,7 +43,7 @@ With the saved block `experiments` set to `{ "__resolveType": "split-traffic", "
|
|
|
43
43
|
- Order is the logic. Put narrow rules first and `always` last. With no `always`, a visitor that matches no rule gets `undefined` for that slot.
|
|
44
44
|
- Prefer `experiment` and `campaign` over request-reading rules. The binding decides them once at the edge and the page cache keys on them. A rule that reads a cookie, a header or the location changes the page by something the cache key does not hold (see [`caching-variants.md`](./references/caching-variants.md)).
|
|
45
45
|
- Keep a test's name stable. A visitor's side is a hash of the test name and their id, so renaming a test re-draws everyone.
|
|
46
|
-
-
|
|
46
|
+
- A/B tests live only in the saved block `experiments`. v7's `random` has no port: move each v7 random test there, with `experiment` rules.
|
|
47
47
|
|
|
48
48
|
## Reading results
|
|
49
49
|
|
|
@@ -8,7 +8,7 @@ This page covers the variant side of caching. The `deco-storefront-caching` skil
|
|
|
8
8
|
|
|
9
9
|
On every page and server-function request, before any cache lookup, the binding:
|
|
10
10
|
|
|
11
|
-
1. reads the visitor (`readVisitor`: the `
|
|
11
|
+
1. reads the visitor (`readVisitor`: the `deco_vid` cookie, or a new visitor with a fresh id);
|
|
12
12
|
2. decides every test of `experiments` and every campaign of `campaigns` for that visitor and that moment;
|
|
13
13
|
3. hands those **assignments** to the cache and to the page, which renders exactly them and decides nothing again.
|
|
14
14
|
|
|
@@ -28,8 +28,6 @@ On v7, a cached page decided the variant for every new visitor who hit it until
|
|
|
28
28
|
|
|
29
29
|
v8's `experiment` rule does not have this problem. Each new visitor gets an id and a roll at the edge before the cache lookup, and the lookup uses their assignments. Two new visitors on different sides read different entries.
|
|
30
30
|
|
|
31
|
-
v7's sticky `random` from `@decocms/compat-v7` still decides during render. A response that sets `deco_segment` must never be stored, so a visitor's first page of a random test is always rendered fresh. Then `cohortSegment(request)` puts their group in the key. Moving the test into `experiments` removes both costs.
|
|
32
|
-
|
|
33
31
|
## Rule by rule
|
|
34
32
|
|
|
35
33
|
| Rule | In the key? | What to do |
|
|
@@ -41,7 +39,6 @@ v7's sticky `random` from `@decocms/compat-v7` still decides during render. A re
|
|
|
41
39
|
| `queryString` (compat) | Depends on your key | The example drops tracking parameters (`utm_*` and the like) from the key, so a rule on them shows one visitor's variant to another |
|
|
42
40
|
| `host` (compat) | Depends on your key | The example keys on the full URL, host included. Safe only when your key does too |
|
|
43
41
|
| `cookie`, `location` (compat) | No | Add the value to the key, skip caching for those pages, or personalize in the browser |
|
|
44
|
-
| `random` (compat) | Through `cohortSegment` | See above; prefer `experiments` |
|
|
45
42
|
| A custom rule that reads the request | No | Same as `cookie` |
|
|
46
43
|
| A custom rule on `currentClient().date` | No | The page keeps the variant of the moment it was cached until it expires. Use a campaign instead |
|
|
47
44
|
|
|
@@ -56,7 +53,7 @@ Signed-in, cart and account content belongs in option 3 or uncached. Never put a
|
|
|
56
53
|
## Checklist: a variant page misses the cache or shows the wrong arm
|
|
57
54
|
|
|
58
55
|
1. **Is it a preview?** A `?__draft=` link or the draft cookie never reaches `pageCache` (see [`draft-preview.md`](./draft-preview.md)).
|
|
59
|
-
2. **Does the response set a cookie?** The worker-entry example never stores a response that sets one (other than `_deco_bucket`). The worker adds the visitor's own cookie after `pageCache`, so that one does not count.
|
|
56
|
+
2. **Does the response set a cookie?** The worker-entry example never stores a response that sets one (other than `_deco_bucket`). The worker adds the visitor's own cookie after `pageCache`, so that one does not count.
|
|
60
57
|
3. **Does a rule read the request?** List the rules on the page (follow saved rule blocks too) and check each against the table above.
|
|
61
58
|
4. **How many tests are running?** `2^n` entries per page split the hits.
|
|
62
59
|
5. **Is the wrong arm stable for one URL?** A rule reads something that is not in the key. Compare the same URL with two different values of the suspect cookie or header.
|
|
@@ -26,7 +26,7 @@ Put the control last, under `always`.
|
|
|
26
26
|
|
|
27
27
|
### How a visitor is assigned
|
|
28
28
|
|
|
29
|
-
- A visitor has an id: 16 random bytes as 22 base64url characters, stored in the `
|
|
29
|
+
- A visitor has an id: 16 random bytes as 22 base64url characters, stored in the `deco_vid` cookie for a year. The cookie is not `HttpOnly`, so an analytics script can read it.
|
|
30
30
|
- For each test, the visitor's roll is a hash of `<test name>:<id>` (MurmurHash3, in `bucketing.ts`), a fixed number from 0 to 99.99. The visitor is in the test when the roll is below the percentage.
|
|
31
31
|
- Nothing per test is stored. One id serves every test, a new test needs no new state, and two tests are independent of each other.
|
|
32
32
|
- The decision is the same on a server, in a browser and in an app: `assign(experiments, visitor)` is a pure function.
|
|
@@ -56,7 +56,7 @@ This gives a safe launch path:
|
|
|
56
56
|
|
|
57
57
|
### Visitors from v7
|
|
58
58
|
|
|
59
|
-
|
|
59
|
+
v8 neither reads nor writes v7's `deco_segment` cookie, so its stored decisions are not honoured: a visitor with only that cookie is a first visit, with a new id, and is drawn again. Move each v7 random test into `experiments` under the same name, so its results keep their name (the `deco-v7-to-v8-migration` skill reports each one); `@decocms/compat-v7` has no `random` to register.
|
|
60
60
|
|
|
61
61
|
## Campaigns
|
|
62
62
|
|
|
@@ -99,6 +99,6 @@ v8 decides who sees what. It does not record conversions, and its analytics modu
|
|
|
99
99
|
|
|
100
100
|
- On TanStack, `requestAssignments()` from `@decocms/tanstack/server` returns each test on or off for the request, as the worker decided it. Pass the arms the page rendered to your analytics events.
|
|
101
101
|
- On any binding, the page's own client gives the same answer: `const [tests] = await client.resolve("experiments")` gives each test's name and `true` or `false`, never a percentage.
|
|
102
|
-
- In the browser, the `
|
|
102
|
+
- In the browser, the `deco_vid` cookie holds the visitor; `parseVisitor` and `assign` from `@decocms/blocks/experiments` give the same answer as the server for a given `experiments` block.
|
|
103
103
|
|
|
104
104
|
Count users, not sessions: the id is per visitor. Then use the `ab-testing` skill in decocms/skills to plan the sample size, check the sample ratio and read significance.
|
|
@@ -37,7 +37,7 @@ What follows from that:
|
|
|
37
37
|
|
|
38
38
|
- **Order is the logic.** Narrow rules first, `always` last. A `never` rule is how the editor hides a variant.
|
|
39
39
|
- **No fallback, no value.** Without an `always` at the end, a visitor that matches nothing gets `undefined`. Sometimes that is the goal ("desktop only"), often it is a bug.
|
|
40
|
-
- **Later rules have no side effects.** A rule after the winner never runs.
|
|
40
|
+
- **Later rules have no side effects.** A rule after the winner never runs.
|
|
41
41
|
- **Rules run in sequence, not in parallel.** Each async rule waits for the one before it. A slow rule early in the list delays the whole slot. The built-in `experiment` and `campaign` read a saved block once per client, however many rules ask.
|
|
42
42
|
- **Results are memoized per request.** The resolver keeps one result per block function and inputs for the life of a client, so two identical rules on one page run once. Treat results as read-only.
|
|
43
43
|
- **A rule that throws fails the block** with `BLOCK_FAILED`. v7's matchers from `@decocms/compat-v7/matchers` catch their own errors and answer `false`, as v7 did. A site's own rule should do the same if a failure should mean "no match" (see [`custom-matchers.md`](./custom-matchers.md)).
|
|
@@ -15,7 +15,6 @@ Use them for content migrated from v7. For new A/B tests and dates, prefer the b
|
|
|
15
15
|
| `queryString` | `website/matchers/queryString.ts` | Query parameters, with `Exists`, `Equals`, `Greater`, `GreaterOrEquals`, `Lesser`, `LesserOrEquals`, `Includes` |
|
|
16
16
|
| `location` | `website/matchers/location.ts` | Country, region, city or coordinates, included or excluded. Reads the `cf-*` headers, then the Workers `request.cf`, then the `__cf_geo_*` cookies |
|
|
17
17
|
| `multi` | `website/matchers/multi.ts` | `op: "and"` or `"or"` over its `matchers`. No rules matches everyone |
|
|
18
|
-
| `random` | `website/matchers/random.ts` | v7's sticky random: a `traffic` share (0 to 1, default 0.5) keyed on a `cohort` |
|
|
19
18
|
| `environment` | `website/matchers/environment.ts` | Always throws: it read the process environment, which no v8 package does. Register your own rule under that name |
|
|
20
19
|
|
|
21
20
|
`always` and `never` are v8 built-ins, and v7's names for them are aliases (see [`multivariate.md`](./multivariate.md)). v7's date matcher became the `campaign` rule and the saved block `campaigns`.
|
|
@@ -29,42 +28,31 @@ Every matcher except `multi` and `environment` takes the request as a second arg
|
|
|
29
28
|
```ts
|
|
30
29
|
// the block map
|
|
31
30
|
import type { Blocks } from "@decocms/blocks";
|
|
32
|
-
import { device, type DeviceProps
|
|
31
|
+
import { device, type DeviceProps } from "@decocms/compat-v7/matchers";
|
|
33
32
|
import { matcherContext } from "@decocms/compat-v7/tanstack/server";
|
|
34
33
|
|
|
35
34
|
export default {
|
|
36
35
|
"website/matchers/device.ts": (props: DeviceProps) => device(props, matcherContext()),
|
|
37
|
-
"website/matchers/random.ts": (props: RandomProps) => random(props, matcherContext()),
|
|
38
36
|
} satisfies Blocks;
|
|
39
37
|
```
|
|
40
38
|
|
|
41
|
-
- `matcherContext(pageUrl?)` gives the matcher the request being served (TanStack Start's `getRequest()`)
|
|
39
|
+
- `matcherContext(pageUrl?)` gives the matcher the request being served (TanStack Start's `getRequest()`) and the page's URL, one context per request and URL.
|
|
42
40
|
- On a client-side navigation the request is the server-function call, not the page. Pass the page's URL there: `matcherContext(new URL(href, request.url))`. Without it, the call throws instead of matching `/_serverFn/…`.
|
|
43
|
-
- After the page resolved, in the page's server function, call `commitSegmentCookie()` to set `deco_segment` with the decisions `random` made. It sets nothing when the cookie already says the same.
|
|
44
|
-
- `cohortSegment(request)` gives v7's A/B split of the cache key (`{ abf: <token> }` for a visitor in a test, `{}` otherwise). Spread it into the segment of the site's page cache.
|
|
45
41
|
|
|
46
42
|
## Wiring on Next.js
|
|
47
43
|
|
|
48
44
|
```ts
|
|
49
45
|
// the block map
|
|
50
46
|
import { matcherContext } from "@decocms/compat-v7/nextjs/server";
|
|
51
|
-
"website/matchers/
|
|
47
|
+
"website/matchers/device.ts": async (props: DeviceProps) => device(props, await matcherContext()),
|
|
52
48
|
```
|
|
53
49
|
|
|
54
50
|
- The matchers need the page's URL. Forward it from the proxy with `pageUrlRequestHeaders` from `@decocms/compat-v7/nextjs/proxy`, or pass it to `matcherContext(url)`.
|
|
55
|
-
- Render `<SegmentCookie />` from `@decocms/compat-v7/nextjs/server` as the last child of the page, after the content resolved. A server component cannot set a cookie, so it renders a one-line script (and an effect after a client-side navigation) that sets it.
|
|
56
51
|
- A page that reads the request is dynamic: Next never shares it between visitors. Keep a CDN in front from caching it too.
|
|
57
52
|
|
|
58
|
-
##
|
|
53
|
+
## v7's `random`
|
|
59
54
|
|
|
60
|
-
-
|
|
61
|
-
- The cookie is keyed on the **cohort**: in v7, the name of the saved matcher block. A v8 block does not know its own name, so the name travels in the `cohort` prop. Set it to the v7 saved block's name. The migration script does not register `random` or fill `cohort`: it reports each random test to move into `experiments`. A random rule written inline uses `website/matchers/random.ts` as its cohort, as v7 did.
|
|
62
|
-
- Keep the cohort when changing the share. Renaming it puts every visitor in a new test.
|
|
63
|
-
- `decideRandom(props, request)` returns `{ value, isFresh, setCookie }` when you need the decision and the cookie together.
|
|
64
|
-
- A response that sets `deco_segment` must not be cached for other visitors.
|
|
65
|
-
- Inside `multi`, a `random` is sticky too. v7 drew it again on every request.
|
|
66
|
-
|
|
67
|
-
The better path for a v7 random test is to move it into the saved block `experiments` under the same name, so visitors keep their groups and the binding owns the cookie. Do not run both on one site.
|
|
55
|
+
`@decocms/compat-v7` has no `random`, and v8 neither reads nor writes v7's `deco_segment` cookie. A rule of type `website/matchers/random.ts` fails with `UNKNOWN_BLOCK` until it is moved: put the test in the saved block `experiments` (type `split-traffic`, a whole percentage 0 to 100; v7's `traffic: 0.3` is `30`) under the v7 saved block's name, and write each rule as `{ "__resolveType": "experiment", "name": "<test>" }` (see [`experiments-and-campaigns.md`](./experiments-and-campaigns.md)). Visitors are drawn again on v8. The migration script reports each random test to move.
|
|
68
56
|
|
|
69
57
|
## The legacy-origin split
|
|
70
58
|
|
|
@@ -42,6 +42,29 @@ export interface AnalyticsClientOptions {
|
|
|
42
42
|
heatmapRate?: number;
|
|
43
43
|
/** Errors module: cross-origin script hosts that count as the site's own. */
|
|
44
44
|
errorHosts?: string[];
|
|
45
|
+
/**
|
|
46
|
+
* The visitor's A/B tests as the page rendered them: each test of the saved `experiments`
|
|
47
|
+
* block on or off, exactly the map that decided the page (on TanStack, what the worker
|
|
48
|
+
* decided, `requestAssignments(request)?.experiments`). Every event then carries each test's
|
|
49
|
+
* arm, `on` or `off`, in `exp`, the first page view included, and the collector stores it as
|
|
50
|
+
* it stores any `exp`. Passing the decision rather than an id keeps what is measured equal to
|
|
51
|
+
* what was shown, a preview's switched tests and a release change included. Leave it unset
|
|
52
|
+
* on a preview, whose switched tests are no visitor's.
|
|
53
|
+
*/
|
|
54
|
+
experiments?: Readonly<Record<string, boolean>>;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/** The decided tests as the collector's `exp` values, `on` or `off`; non-boolean entries left out. */
|
|
58
|
+
function armsOf(
|
|
59
|
+
experiments: Readonly<Record<string, boolean>> | undefined,
|
|
60
|
+
): Record<string, string> {
|
|
61
|
+
const arms = Object.create(null) as Record<string, string>;
|
|
62
|
+
if (typeof experiments !== "object" || experiments === null) return arms;
|
|
63
|
+
for (const name of Object.keys(experiments)) {
|
|
64
|
+
const on = experiments[name];
|
|
65
|
+
if (typeof on === "boolean") arms[name] = on ? "on" : "off";
|
|
66
|
+
}
|
|
67
|
+
return arms;
|
|
45
68
|
}
|
|
46
69
|
|
|
47
70
|
/** One loader per file, so a bundler splits each module into its own chunk. */
|
|
@@ -73,7 +96,13 @@ export async function startAnalytics(
|
|
|
73
96
|
if (typeof window === "undefined") return null;
|
|
74
97
|
const w = window as unknown as Record<string, any>;
|
|
75
98
|
try {
|
|
76
|
-
|
|
99
|
+
const arms = armsOf(options.experiments);
|
|
100
|
+
if (w.__dqBooted) {
|
|
101
|
+
// The tag booted first: its API is the client, so the arms go through it.
|
|
102
|
+
if (typeof w.__dq?.track !== "function") return null;
|
|
103
|
+
for (const name of Object.keys(arms)) w.__dq.setExperiment?.(name, arms[name]);
|
|
104
|
+
return w.__dq;
|
|
105
|
+
}
|
|
77
106
|
|
|
78
107
|
// The same fields the collector writes ahead of `/_dq/a.js`, and the same precedence: what
|
|
79
108
|
// the page already set on `window.__dq` wins. `q` is held back and replayed below, once
|
|
@@ -94,6 +123,9 @@ export async function startAnalytics(
|
|
|
94
123
|
...(options.errorHosts?.length ? { er: options.errorHosts } : {}),
|
|
95
124
|
},
|
|
96
125
|
page,
|
|
126
|
+
// The page's own map (another script's tests) is kept; on a name both carry, the arm the
|
|
127
|
+
// page rendered wins. Set before core boots, so the first page view carries it.
|
|
128
|
+
Object.keys(arms).length ? { x: { ...(page.x as object), ...arms } } : {},
|
|
97
129
|
{ q: [] },
|
|
98
130
|
);
|
|
99
131
|
|
|
@@ -102,6 +134,9 @@ export async function startAnalytics(
|
|
|
102
134
|
if (typeof w.__dq.track !== "function") return null;
|
|
103
135
|
|
|
104
136
|
for (const name of new Set(options.modules ?? [])) await MODULES[name]?.();
|
|
137
|
+
// A module may set a test of its own on load: `deco` reads v7's `deco_segment`, which a
|
|
138
|
+
// migrated visitor still carries and v8 never rewrites. The arm the page rendered wins.
|
|
139
|
+
for (const name of Object.keys(arms)) w.__dq.setExperiment?.(name, arms[name]);
|
|
105
140
|
for (const r of queued) w.__dq.q?.push?.(r);
|
|
106
141
|
return w.__dq;
|
|
107
142
|
} catch {
|
package/src/v8/client.ts
CHANGED
|
@@ -251,18 +251,7 @@ function copyVisitor(visitor: Visitor | null | undefined): Visitor | null {
|
|
|
251
251
|
if (typeof visitor !== "object" || visitor === null || typeof visitor.id !== "string") {
|
|
252
252
|
return null;
|
|
253
253
|
}
|
|
254
|
-
|
|
255
|
-
Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
|
|
256
|
-
const copy: Visitor = {
|
|
257
|
-
id: visitor.id,
|
|
258
|
-
active: Object.freeze(strings(visitor.active)) as string[],
|
|
259
|
-
inactiveDrawn: Object.freeze(strings(visitor.inactiveDrawn)) as string[],
|
|
260
|
-
pct: Object.freeze(Object.assign(Object.create(null), visitor.pct)),
|
|
261
|
-
};
|
|
262
|
-
if (typeof visitor.exp === "object" && visitor.exp !== null) {
|
|
263
|
-
copy.exp = Object.freeze(Object.assign(Object.create(null), visitor.exp));
|
|
264
|
-
}
|
|
265
|
-
return Object.freeze(copy);
|
|
254
|
+
return Object.freeze({ id: visitor.id });
|
|
266
255
|
}
|
|
267
256
|
|
|
268
257
|
function asCMSError(error: unknown): CMSError {
|