@coframe/sdk 1.1.46 → 1.1.48

package/README.md

@@ -140,6 +140,178 @@ const projectData = serverData?.project
 
 Pass `projectData` into `<CoframeProvider>` to avoid the extra client-side project fetch and personalize on first paint.
 
+### Server-side assignment
+
+Use `getExperimentAssignment()` when the server must know one experiment's
+variant before rendering or calling an upstream service. Edge performs the full
+assignment; the package never falls back to local bucketing.
+
+```ts
+import {
+  generateUserToken,
+  getExperimentAssignment,
+} from '@coframe/sdk/server'
+
+// Next.js `request.cookies.get()` returns `{ name, value }`; other runtimes
+// return the string. Either way `userToken` must be the string value.
+const existingToken = request.cookies.get('coframe.user.token')?.value
+const userToken = existingToken ?? generateUserToken()
+
+if (!existingToken) {
+  // Do not set `httpOnly`: the browser SDK reads this cookie to reuse the
+  // same identity. An HttpOnly token makes the browser generate a new one and
+  // bucket differently, with no error.
+  response.cookies.set('coframe.user.token', userToken, {
+    path: '/',
+    secure: true,
+    sameSite: 'lax',
+    maxAge: 400 * 24 * 60 * 60,
+  })
+}
+
+const assignment = await getExperimentAssignment({
+  projectId: 'your-project-id',
+  experimentId: 'your-experiment-id',
+  userToken,
+  currentUrl: request.url,
+  headers: request.headers,
+})
+
+const upstreamVersion =
+  assignment?.variant?.slug === 'variant-2' ? 'v2' : 'v1'
+```
+
+The package derives visitor context from an allowlist of request headers.
+Explicit `userAgent`, `languages`, `browserPlatform`, `country`, `region`,
+`city`, `device`, `botScore`, `verifiedBotCategory`, `clientIp`,
+`userVisitCount`, and `userContext` options override the derived values. Only
+the lane cookie is forwarded to Edge; authorization and application cookies are
+not forwarded. `clientIp` is used only for existing blocklist targeting.
+
+Geography, device, bot score, and client IP are read from `cf-*` request
+headers. Cloudflare adds `cf-ipcountry` and `cf-connecting-ip` to every
+request that reaches your origin; `cf-region-code` and `cf-ipcity` need the
+"Add visitor location headers" Managed Transform, `cf-device-type` needs
+"cache by device type", and `cf-bot-score` needs Bot Management plus a
+Transform Rule. If your server is not behind Cloudflare, or a header is not
+enabled, that value is missing: the country becomes `unknown`, country
+audiences never match, and the device falls back to the user agent. Pass
+`country`, `region`, `city`, and `device` explicitly in that case, from
+whatever geo source your stack already has. Values are forwarded verbatim and
+audiences compare them exactly, so use Cloudflare's spelling: `country` is the
+uppercase ISO 3166-1 alpha-2 code (`US`, not `us`), `region` the ISO 3166-2
+subdivision code (`CA`), and `device` one of `desktop`, `mobile`, `tablet`.
+
+When a result is available, pass its project snapshot to the provider. The
+browser reads the same standard token cookie and runs its existing assignment
+flow without fetching project data again.
+
+```tsx
+<CoframeProvider
+  projectConfig={{ projectId: 'your-project-id' }}
+  projectData={assignment?.projectData}
+>
+  {children}
+</CoframeProvider>
+```
+
+`assignment` is `undefined` when the call failed (see below), so read
+`projectData` with optional chaining and decide there whether the browser may
+initialize on its own.
+
+`generateUserToken()` uses Web Crypto when available and falls back to a
+non-cryptographic UUID generator in server runtimes without Web Crypto. The
+token is assignment identity, not an authentication credential. It remains
+stable until its cookie is removed, expires, or is replaced.
+The separate visit count uses the SDK's existing two-hour visit boundary. The
+package only reads the visit cookies the browser SDK writes (`coframe.cvc`,
+`coframe.lastVisitTime`) and never sets them, so without the browser SDK running
+after consent the count stays at 1 and `returning` audiences never match.
+
+The result contains either one `variant` or `variant: null` with a structured
+reason (`experiment_not_found`; `not_assigned`, which also covers a visitor
+held out of this experiment or of the whole project by a holdout and renders
+the default experience in the browser too; `unsupported_experiment_type` for
+CMAB targets; `preview_active` for URL previews; a newer Edge may add reasons,
+so treat any reason you do not know as "no variant"). Both forms include the exact `projectData` snapshot used by Edge, so the
+browser can initialize from that snapshot. The snapshot also carries the
+normalized language, platform, and visit-count values used by Edge. The browser
+uses those values only for its initial assignment and returns to its normal
+browser-derived context for later SPA navigations. In every case without a
+variant, use the default upstream experience.
+
+The function returns `undefined` for transport, timeout (`timeoutMs`,
+default 1500 ms), Edge, or response validation failures, and when
+`currentUrl` carries `cf_disable`. Handle that state explicitly. Invalid options are a
+programming error and throw instead: an empty `projectId`, `experimentId` or
+`userToken`, a `currentUrl` that is not an absolute URL (Express and Fastify
+`req.url` is a path, build the full URL first), out-of-range `languages`,
+`device`, `botScore`, `timeoutMs` and `userVisitCount` values, any string
+option longer than its limit (4096 characters for URLs, 2048 for the user
+agent, 200 for `projectId`, 512 for `experimentId` and `userToken`), or a
+`userContext` that serializes to more than 4096 bytes (`userContext is too large`). Values derived from
+request headers are clamped instead. To preserve server/browser
+consistency for the response, do not let the browser independently fetch project
+data and assign an experiment after the server has fallen back to its default.
+Applications that accept that possible mismatch may instead initialize the
+browser normally as their fail-open policy.
+
+#### What Edge cannot evaluate
+
+Server assignment runs the same deterministic logic as the browser, with the
+same token, the same project snapshot, and the same visitor context. The
+browser then reaches the same bucket because every input is the same. Five
+kinds of input only exist in the page, so Edge cannot evaluate them:
+
+- **JavaScript targeting.** A `js_function` condition (custom JavaScript that
+  reads a page value, a cookie, `localStorage`, or the `dataLayer`) runs only
+  in the browser, whether it sits on an audience or on a frame's activation
+  condition. Edge treats it as not matched.
+  - If the target experiment itself uses a JavaScript audience, the result is
+    `variant: null` with reason `not_assigned`. Do not use JavaScript audiences
+    on experiments you resolve on the server.
+  - Experiments in the same frame are evaluated in order and the first match
+    wins. If a JavaScript-targeted experiment sits **ahead of the target in
+    the same frame**, Edge skips it and assigns the target, while the browser
+    can match it and skip the target. Keep JavaScript-targeted experiments out
+    of the target experiment's frame, or place them after the target.
+  - The same applies to a JavaScript-targeted experiment that shares a
+    **lane** with the target, wherever it sits: lane winners are drawn from
+    the experiments the visitor can reach, and Edge cannot tell whether that
+    one is reachable. Keep JavaScript-targeted experiments out of the target's
+    lane.
+- **CMAB experiments.** A target CMAB experiment returns `variant: null` with
+  reason `unsupported_experiment_type`.
+- **URL fragments.** A server never sees the `#fragment` of the page URL, and
+  the browser re-evaluates the snapshot with its full `location.href`. Frames
+  that use `base_url_matches` ignore query and fragment and are safe; an exact
+  `url` condition compares both, and a `url_regex` runs against the full
+  `location.href` in the browser, so pass the same URL the browser will have,
+  without a fragment, and avoid regexes anchored on the end of the URL.
+- **Previews.** Previews are browser-only. A `coframe_variant_id` URL
+  parameter reaches Edge, but the published preview payloads do not name the
+  experiment a variant belongs to, so the server answers `variant: null` with
+  reason `preview_active` and the browser renders the preview from the
+  returned snapshot. A preview kept across navigation by the Preview Session
+  tool lives in the browser's `sessionStorage` and never reaches Edge; the
+  browser discards the snapshot and fetches its own project. Both affect
+  preview users only; render the default upstream experience.
+- **Lane state.** Edge reads lane claims from the `coframe.lanes` cookie only.
+  Before cookie consent the browser keeps claims in `localStorage`, which the
+  server cannot see, and the server does not persist the claims Edge commits.
+  Laned experiments therefore agree once the browser has written the cookie,
+  not for a visitor without cookie consent.
+
+Audience conditions based on URL (`base_url_matches`), country, device,
+language, platform, visit type, search, time, allocation, or `userContext`
+evaluate identically on both sides, as does bot cloaking. For platform, Edge derives the same
+`navigator.platform` family the browser reports (a `Linux …` string on Android,
+for example `Linux armv8l`), or takes an explicit `browserPlatform` option.
+
+If the application uses a custom identity cookie, call `setUserToken()` before
+browser initialization with `waitForUserToken: true`. That integration must also
+keep visit and lane state aligned between the server and browser.
+
 ## Feature flags and remote config
 
 Browser Feature Flags use the existing public `projectId` and receive only
@@ -453,6 +625,8 @@ Modern resolution modes handle package subpath exports more reliably.
 ### `@coframe/sdk/server`
 
 - `getProjectData(options)`
+- `getExperimentAssignment(options)`
+- `generateUserToken()`
 - `evaluateFlags(options)`
 - `getFeatureFlag(key, options)` / `isFeatureEnabled(key, options)`
 - `getFeatureFlagPayload(key, options)` / `getRemoteConfig(key, options)`

package/dist/pkg/cf.cjs.js

@@ -302,9 +302,11 @@ const generateUUID = () => {
     const cryptoObject = (_a = getGlobalScope()) === null || _a === void 0 ? void 0 : _a.crypto;
     if (cryptoObject === null || cryptoObject === void 0 ? void 0 : cryptoObject.randomUUID)
         return cryptoObject.randomUUID();
+    const randomByte = (cryptoObject === null || cryptoObject === void 0 ? void 0 : cryptoObject.getRandomValues)
+        ? () => cryptoObject.getRandomValues(new Uint8Array(1))[0]
+        : () => Math.floor(Math.random() * 256);
     return `${1e7}${ -1e3}${ -4e3}${ -8e3}${ -1e11}`.replace(/[018]/g, (c) => {
-        var _a, _b;
-        const randomValue = (_b = (_a = cryptoObject === null || cryptoObject === void 0 ? void 0 : cryptoObject.getRandomValues) === null || _a === void 0 ? void 0 : _a.call(cryptoObject, new Uint8Array(1))[0]) !== null && _b !== void 0 ? _b : 0;
+        const randomValue = randomByte();
         return (c ^
             (randomValue & (15 >> (c / 4)))).toString(16);
     });
@@ -371,16 +373,30 @@ const getOrGenerateUserToken = () => {
 const setUserTokenCookie = (uuid, logger) => {
     setCookie(USER_TOKEN_COOKIE_KEY, uuid, logger);
 };
+const VISIT_BOUNDARY_MS = 2 * 60 * 60 * 1000;
+function startsNewVisit(lastVisitTime, now) {
+    return !lastVisitTime || now - lastVisitTime > VISIT_BOUNDARY_MS;
+}
+function nextVisitCount(existing, lastVisitTime, now) {
+    return startsNewVisit(lastVisitTime, now) ? existing + 1 : existing;
+}
+function parseNonNegativeInt(raw) {
+    if (!raw || !/^\d+$/.test(raw))
+        return undefined;
+    const parsed = Number(raw);
+    return parsed <= 9007199254740991 ? parsed : undefined;
+}
+function parseVisitCount(raw) {
+    var _a;
+    return (_a = parseNonNegativeInt(raw)) !== null && _a !== void 0 ? _a : 0;
+}
 const trackVisitCookie = (logger) => {
-    const visitCountString = getCookie(VISIT_COUNT_COOKIE_KEY);
-    const lastVisitTime = Number.parseInt(getCookie(LAST_VISIT_TIME_KEY), 10);
+    const existing = parseVisitCount(getCookie(VISIT_COUNT_COOKIE_KEY));
+    const lastVisitTime = parseVisitCount(getCookie(LAST_VISIT_TIME_KEY));
     const currentTime = Date.now();
-    const twoHours = 2 * 60 * 60 * 1000;
-    if (!lastVisitTime || currentTime - lastVisitTime > twoHours) {
-        const visitCount = visitCountString
-            ? Number.parseInt(visitCountString, 10) + 1
-            : 1;
-        setCookie(VISIT_COUNT_COOKIE_KEY, visitCount.toString(), logger);
+    const next = nextVisitCount(existing, lastVisitTime, currentTime);
+    if (next !== existing) {
+        setCookie(VISIT_COUNT_COOKIE_KEY, next.toString(), logger);
         setCookie(LAST_VISIT_TIME_KEY, currentTime.toString(), logger);
     }
 };
@@ -2069,6 +2085,7 @@ const applyVariantChanges = (variantElements, currentUrl, logger, nonce, lifecyc
         ? lifecycleContext.runtime.createVariantSession({
             batchId: lifecycleContext.batchId,
             variantId: variant.id,
+            experimentId: variant.experiment_id,
         })
         : null;
     if (!variant.modifications ||
@@ -2106,7 +2123,7 @@ const applyVariantChanges = (variantElements, currentUrl, logger, nonce, lifecyc
             });
         }
         else if (selectedElement instanceof HTMLElement) {
-            selectedElement.setAttribute('coframe-exp-id', variant.id);
+            selectedElement.setAttribute('coframe-exp-id', variant.experiment_id);
         }
     }
     return true;
@@ -2292,6 +2309,16 @@ function murmurHash3_x86_32(key, seed) {
     return h1 >>> 0;
 }
 
+function parseLaneCookie(raw) {
+    if (!raw)
+        return {};
+    try {
+        return parseClaims(decodeURIComponent(raw));
+    }
+    catch (_a) {
+        return parseClaims(raw);
+    }
+}
 function parseClaims(raw) {
     if (!raw)
         return {};
@@ -2725,7 +2752,7 @@ function checkAllAudiences(metadata, ctx) {
         const audience = ctx.project.audiences[audienceId];
         if (!audience)
             continue;
-        const activated = checkActivationCondition(audience.selector, ctx.personalizationHeaders, ctx.currentPageUrl, ctx.languages, ctx.browserPlatform, ctx.userToken, ctx.userVisitCount, (js, args) => executeJs(js, args, { isExpression: true, nonce: ctx.nonce }), ctx.logger);
+        const activated = checkActivationCondition(audience.selector, ctx.personalizationHeaders, ctx.currentPageUrl, ctx.languages, ctx.browserPlatform, ctx.userToken, ctx.userVisitCount, ctx.runJsFunction, ctx.logger);
         if (activated === false)
             return false;
         if (activated !== true)
@@ -2733,8 +2760,12 @@ function checkAllAudiences(metadata, ctx) {
     }
     return result;
 }
-async function getVariantsAndElements(personalizationHeaders, project, previewVariantId, userToken, currentPageUrl, languages, browserPlatform, logger, nonce, laneClaims = {}, silentFallback = false, chooseCmabVariants) {
-    var _a;
+function audiencesPass(metadata, ctx) {
+    const result = checkAllAudiences(metadata, ctx);
+    return ctx.unknownIsInactive ? result === true : result !== false;
+}
+async function getVariantsAndElements(personalizationHeaders, project, previewVariantId, userToken, currentPageUrl, languages, browserPlatform, logger, nonce, laneClaims = {}, silentFallback = false, chooseCmabVariants, userVisitCountOverride, runtime = {}) {
+    var _a, _b;
     const experimentsInfo = [];
     const cloakBot = !!((_a = project.settings) === null || _a === void 0 ? void 0 : _a.bot_cloaking_enabled) &&
         personalizationHeaders['x-is-bot'] === 'true';
@@ -2746,7 +2777,11 @@ async function getVariantsAndElements(personalizationHeaders, project, previewVa
             laneClaims: meClaims,
         };
     };
-    const userVisitCount = Number.parseInt(getCookie(VISIT_COUNT_COOKIE_KEY) || '0', 10);
+    const userVisitCount = userVisitCountOverride !== null && userVisitCountOverride !== void 0 ? userVisitCountOverride : parseVisitCount(getCookie(VISIT_COUNT_COOKIE_KEY));
+    const evaluateJsFunctions = (_b = runtime.evaluateJsFunctions) !== null && _b !== void 0 ? _b : true;
+    const runJsFunction = evaluateJsFunctions
+        ? (js, args) => executeJs(js, args, { isExpression: true, nonce })
+        : undefined;
     const ctx = {
         project,
         personalizationHeaders,
@@ -2755,8 +2790,9 @@ async function getVariantsAndElements(personalizationHeaders, project, previewVa
         languages,
         browserPlatform,
         userVisitCount,
-        nonce,
         logger,
+        runJsFunction,
+        unknownIsInactive: !evaluateJsFunctions,
     };
     const validatedClaims = validateClaims(laneClaims, project.lanes);
     const previewVariantIds = splitPreviewVariantIds(previewVariantId);
@@ -2811,27 +2847,24 @@ function activateFrames(ctx) {
     return ctx.project.frames.filter((frame) => {
         if (!frame.experiments)
             return false;
-        const frameActivated = checkActivationCondition(frame.activation_condition, ctx.personalizationHeaders, ctx.currentPageUrl, ctx.languages, ctx.browserPlatform, ctx.userToken, ctx.userVisitCount, (js, args) => executeJs(js, args, { isExpression: true, nonce: ctx.nonce }), ctx.logger);
-        if (!frameActivated)
-            return false;
-        return true;
+        const frameActivated = checkActivationCondition(frame.activation_condition, ctx.personalizationHeaders, ctx.currentPageUrl, ctx.languages, ctx.browserPlatform, ctx.userToken, ctx.userVisitCount, ctx.runJsFunction, ctx.logger);
+        return ctx.unknownIsInactive ? frameActivated === true : !!frameActivated;
     });
 }
 async function assignFrames(activeFrames, validatedClaims, ctx, chooseCmabVariants) {
-    var _a;
+    var _a, _b, _c;
     const { project, userToken, logger } = ctx;
     const experimentsInfo = [];
     const variantsAndElements = [];
-    const evalAudiences = (metadata) => checkAllAudiences(metadata, ctx) !== false;
     const audiencePass = new Map();
     const reachableByLane = {};
     for (const frame of activeFrames) {
-        for (const experiment of frame.experiments) {
+        for (const experiment of (_a = frame.experiments) !== null && _a !== void 0 ? _a : []) {
             const metadata = experiment.metadata;
             const laneIds = experimentLaneIds(metadata);
             if (laneIds.length === 0)
                 continue;
-            const passes = evalAudiences(metadata);
+            const passes = audiencesPass(metadata, ctx);
             audiencePass.set(metadata.experiment_id, passes);
             if (passes) {
                 for (const laneId of laneIds) {
@@ -2848,7 +2881,7 @@ async function assignFrames(activeFrames, validatedClaims, ctx, chooseCmabVarian
     let hasActivatedFrames = false;
     for (const frame of activeFrames) {
         let atLeastOneExperimentWasActivated = false;
-        for (const experiment of frame.experiments) {
+        for (const experiment of (_b = frame.experiments) !== null && _b !== void 0 ? _b : []) {
             if (atLeastOneExperimentWasActivated)
                 break;
             const metadata = experiment.metadata;
@@ -2858,7 +2891,7 @@ async function assignFrames(activeFrames, validatedClaims, ctx, chooseCmabVarian
                 continue;
             let activated = audiencePass.get(metadata.experiment_id);
             if (activated === undefined) {
-                activated = evalAudiences(metadata);
+                activated = audiencesPass(metadata, ctx);
             }
             if (!activated)
                 continue;
@@ -2914,7 +2947,7 @@ async function assignFrames(activeFrames, validatedClaims, ctx, chooseCmabVarian
         try {
             mlVariantIds = await chooseCmabVariants(Array.from(cmabMetadataById.values()), userToken);
         }
-        catch (_b) {
+        catch (_d) {
             mlVariantIds = new Map();
         }
     }
@@ -2925,7 +2958,7 @@ async function assignFrames(activeFrames, validatedClaims, ctx, chooseCmabVarian
         }
         const { metadata, variants, elements } = entry;
         let mlVariantId = metadata.type === 'CMAB'
-            ? ((_a = mlVariantIds.get(metadata.experiment_id)) !== null && _a !== void 0 ? _a : null)
+            ? ((_c = mlVariantIds.get(metadata.experiment_id)) !== null && _c !== void 0 ? _c : null)
             : null;
         if (mlVariantId && !variants.some((v) => v.id === mlVariantId)) {
             logger.warn(`CMAB variant ${mlVariantId} not in experiment ${metadata.experiment_id}`, 'cmab_variant_not_found', { experiment_id: metadata.experiment_id });
@@ -2978,9 +3011,12 @@ async function previewVariants(previewVariantIds, validatedClaims, ctx, silentFa
     return uniqueByVariantId([...rolledOutVariants, ...requestedVariants]);
 }
 function findVariants(frames, variantIds) {
-    return frames.flatMap((frame) => frame.experiments.flatMap((experiment) => experiment.variants
-        .filter((variant) => variantIds.includes(variant.id))
-        .map((variant) => ({ variant, elements: frame.elements }))));
+    return frames.flatMap((frame) => {
+        var _a;
+        return ((_a = frame.experiments) !== null && _a !== void 0 ? _a : []).flatMap((experiment) => experiment.variants
+            .filter((variant) => variantIds.includes(variant.id))
+            .map((variant) => ({ variant, elements: frame.elements })));
+    });
 }
 function uniqueByVariantId(items) {
     const seen = {};
@@ -2992,10 +3028,13 @@ function uniqueByVariantId(items) {
     });
 }
 function keepRolledOutExperiments(frames) {
-    return frames.map((frame) => ({
-        ...frame,
-        experiments: frame.experiments.filter((experiment) => experiment.metadata.serving_mode === 'winner'),
-    }));
+    return frames.map((frame) => {
+        var _a;
+        return ({
+            ...frame,
+            experiments: ((_a = frame.experiments) !== null && _a !== void 0 ? _a : []).filter((experiment) => experiment.metadata.serving_mode === 'winner'),
+        });
+    });
 }
 
 function buildSessionContext(isInitialApply) {
@@ -3666,6 +3705,7 @@ async function resolveProject(Coframe, previewVariantId, isSessionVariant, confi
     const queuedHeaders = getQueuedPersonalizationHeaders();
     let personalizationHeaders = queuedHeaders;
     let project = isSessionVariant ? undefined : projectData === null || projectData === void 0 ? void 0 : projectData.project;
+    const assignmentContext = project ? projectData === null || projectData === void 0 ? void 0 : projectData.assignmentContext : undefined;
     if (!project) {
         const edgeResult = await fetchProject(config.projectUrl, Coframe.projectId, config.currentUrl || getCurrentPageUrl(), undefined, config.userContext, previewVariantId || undefined, undefined, (_b = config.referrer) !== null && _b !== void 0 ? _b : getBrowserReferrer());
         personalizationHeaders = mergeClientHeaders(queuedHeaders, edgeResult === null || edgeResult === void 0 ? void 0 : edgeResult.personalizationHeaders);
@@ -3682,6 +3722,7 @@ async function resolveProject(Coframe, previewVariantId, isSessionVariant, confi
     return {
         project,
         personalizationHeaders: personalizationHeaders,
+        ...(assignmentContext ? { assignmentContext } : {}),
     };
 }
 
@@ -4159,7 +4200,7 @@ function setupListeners(Coframe, executionStartTime) {
         for (const variantElement of Coframe.variantsAndElements || []) {
             const variant = variantElement.variant;
             if (!experiencedCoframeIds.has(variant.id)) {
-                const elements = document.querySelectorAll(`[coframe-exp-id="${variant.id}"]`);
+                const elements = document.querySelectorAll(`[coframe-exp-id="${variant.experiment_id}"]`);
                 for (const el of Array.from(elements)) {
                     if (isElementVisible(el)) {
                         el.setAttribute('coframe-experienced', 'true');
@@ -4453,18 +4494,12 @@ function setupSPANavigation(Coframe, project, config, previewVariantId, isSessio
 }
 function readLaneClaims() {
     const cookie = getCookie(LANE_COOKIE_KEY);
-    if (cookie) {
-        try {
-            return parseClaims(decodeURIComponent(cookie));
-        }
-        catch (_a) {
-            return parseClaims(cookie);
-        }
-    }
+    if (cookie)
+        return parseLaneCookie(cookie);
     try {
         return parseClaims(localStorage.getItem(LANE_COOKIE_KEY));
     }
-    catch (_b) {
+    catch (_a) {
         return {};
     }
 }
@@ -4479,14 +4514,17 @@ function persistLaneClaims(claims, logger) {
         setCookie(LANE_COOKIE_KEY, encodeURIComponent(serialized), logger);
     }
 }
-function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant, executionStartTime, analytics, laneStore, runtime) {
+function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant, executionStartTime, analytics, laneStore, runtime, initialAssignmentContext) {
     let isFirstApply = true;
+    let snapshotContext = initialAssignmentContext;
     let applicationId = 0;
     const apply = async (pageUrl, pageProject, personalizationHeaders, signal, deadline) => {
-        var _a, _b;
+        var _a, _b, _c, _d;
         const currentApplication = ++applicationId;
         if (signal === null || signal === void 0 ? void 0 : signal.aborted)
             return 'skipped';
+        const assignmentContext = snapshotContext;
+        snapshotContext = undefined;
         const preview = resolvePreview(pageUrl, previewVariantId, isSessionVariant);
         const chooseCmabVariants = createCmabVariantBatchChooser({
             projectId: Coframe.projectId,
@@ -4497,7 +4535,7 @@ function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant
             disableRemoteAssignment: Boolean(config.projectUrl || config.ingestUrl),
             userContext: config.userContext,
         });
-        const { variantsAndElements, experimentsInfo, hasActivatedFrames, laneClaims, } = await getVariantsAndElements(personalizationHeaders, pageProject, preview.previewVariantId, Coframe.userToken, pageUrl, getBrowserLanguages(), getBrowserPlatform(), Coframe.logger, config.nonce, laneStore.claims, preview.isSessionVariant, chooseCmabVariants);
+        const { variantsAndElements, experimentsInfo, hasActivatedFrames, laneClaims, } = await getVariantsAndElements(personalizationHeaders, pageProject, preview.previewVariantId, Coframe.userToken, pageUrl, (_b = assignmentContext === null || assignmentContext === void 0 ? void 0 : assignmentContext.languages) !== null && _b !== void 0 ? _b : getBrowserLanguages(), (_c = assignmentContext === null || assignmentContext === void 0 ? void 0 : assignmentContext.browserPlatform) !== null && _c !== void 0 ? _c : getBrowserPlatform(), Coframe.logger, config.nonce, laneStore.claims, preview.isSessionVariant, chooseCmabVariants, assignmentContext === null || assignmentContext === void 0 ? void 0 : assignmentContext.userVisitCount);
         if ((signal === null || signal === void 0 ? void 0 : signal.aborted) ||
             currentApplication !== applicationId ||
             (runtime === null || runtime === void 0 ? void 0 : runtime.isDestroyed()) ||
@@ -4505,7 +4543,7 @@ function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant
             return 'skipped';
         if (!signal &&
             runtime &&
-            ((_b = pageProject === null || pageProject === void 0 ? void 0 : pageProject.settings) === null || _b === void 0 ? void 0 : _b.mutation_observer_active) &&
+            ((_d = pageProject === null || pageProject === void 0 ? void 0 : pageProject.settings) === null || _d === void 0 ? void 0 : _d.mutation_observer_active) &&
             !urlsMatch(pageUrl, getCurrentPageUrl(), true))
             return 'stale-route';
         if (!signal && runtime) {
@@ -4551,7 +4589,7 @@ function createApplyVariants(Coframe, config, previewVariantId, isSessionVariant
 async function modifyPage(Coframe, configResult, projectResult, analytics, lifecycle) {
     var _a;
     const { config, timeoutMs, previewVariantId, isSessionVariant, integrationStartTime, executionStartTime, } = configResult;
-    const { project: cdnProject, personalizationHeaders } = projectResult;
+    const { project: cdnProject, personalizationHeaders, assignmentContext, } = projectResult;
     const revealCoordinator = (_a = lifecycle === null || lifecycle === void 0 ? void 0 : lifecycle.revealCoordinator) !== null && _a !== void 0 ? _a : createRevealCoordinator(revealPage, logRevealListenerError(() => Coframe.logger));
     const runtime = lifecycle === null || lifecycle === void 0 ? void 0 : lifecycle.runtime;
     if (runtime && config.waitForHydration) {
@@ -4577,7 +4615,7 @@ async function modifyPage(Coframe, configResult, projectResult, analytics, lifec
     if (!(await ensureBody(Coframe, cdnProject, timeoutMs, config.nonce, revealCoordinator, () => !(runtime === null || runtime === void 0 ? void 0 : runtime.isDestroyed()))))
         return;
     const laneStore = { claims: readLaneClaims() };
-    const applier = createApplyVariants(Coframe, config, previewVariantId, isSessionVariant, executionStartTime, analytics, laneStore, runtime);
+    const applier = createApplyVariants(Coframe, config, previewVariantId, isSessionVariant, executionStartTime, analytics, laneStore, runtime, assignmentContext);
     const initialUrl = getCurrentPageUrl();
     if (runtime) {
         const runtimeUrl = runtime.getState().currentUrl;
@@ -5180,6 +5218,9 @@ function injectOptions(options) {
             projectData: {
                 project: options.projectData.project,
                 personalizationHeaders: (_a = options.projectData.personalizationHeaders) !== null && _a !== void 0 ? _a : {},
+                ...(options.projectData.assignmentContext
+                    ? { assignmentContext: options.projectData.assignmentContext }
+                    : {}),
             },
         });
     }
@@ -5389,6 +5430,7 @@ function createVariantSession(options) {
         getPageState: () => ({ ...options.getPageState() }),
         getState: () => ({ ...state }),
         getVariantId: () => state.variantId,
+        getExperimentId: () => options.experimentId,
         onPage: (event, handler) => subscribe(event, handler, false),
         oncePage: (event, handler) => subscribe(event, handler, true),
         ready() {
@@ -5748,6 +5790,7 @@ function createPageRuntime(options) {
             const session = createVariantSession({
                 sessionId: createId(),
                 variantId: input.variantId,
+                experimentId: input.experimentId,
                 batchId: batch.batchId,
                 routeVersion: batch.routeVersion,
                 getPageState: () => ({ ...state }),