@c15t/react 3.1.0 → 3.2.0

package/docs/integrations/optimizely.md

@@ -0,0 +1,411 @@
+---
+title: Optimizely
+description: Load Optimizely Web Experimentation and Personalization after
+  experience consent with c15t, choose a consent category and understand
+  revocation limits.
+seoTitle: Optimizely cookie consent with c15t
+seoDescription: Gate Optimizely Web Experimentation on experience consent with
+  c15t. Configure the project snippet, handle page flicker and understand reload
+  limits.
+icon: flask-conical
+group: integrations
+---
+
+Optimizely Web runs A/B tests and personalization by changing the page in the
+browser. The c15t `optimizelyWeb` helper waits for `experience` consent before
+it loads the Optimizely Web Experimentation or Personalization snippet. Until
+then, the helper creates no Optimizely global and makes no Optimizely request.
+
+On withdrawal, c15t removes the snippet and reloads the page. The running SDK
+can't be unloaded, so without the reload it keeps changing the page and
+sending events.
+
+## Configure Optimizely
+
+In Optimizely, open **Settings > Implementation** and copy the project number
+just before `.js` in the snippet URL. Replace the example project number below
+with yours. Use one Optimizely snippet per page. Remove the original
+Optimizely snippet and any tag-manager copy so c15t controls when it loads.
+
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
+
+```ts title="src/consent-scripts.ts"
+import { optimizelyWeb } from '@c15t/integrations/optimizely';
+
+export const scripts = [optimizelyWeb({ projectId: '12345678' })];
+```
+
+The default loader URL is `https://cdn.optimizely.com/js/<projectId>.js`.
+
+## Register the scripts
+
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry, so the vendor loads only through c15t.
+
+The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
+quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
+in the Next.js guide, add the helper to that array instead of creating a
+second file.
+The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
+point for your framework below. These are edits to that provider, not a second
+provider.
+
+**Next.js**
+
+Add the configuration to `scripts` in `c15t.config.ts`, next to
+`next.config.ts`:
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+import { scripts } from './src/consent-scripts';
+
+export default defineConsentConfig({ scripts });
+```
+
+Keep the rest of your config, such as `mode` and `routePrefix`, in the
+same call. `ConsentRoot` reads the config in the browser, so the layout
+keeps passing only `state`. App Router, Pages Router and static export all
+read the same file. See
+[Next.js scripts and embeds](https://c15t.com/docs/frameworks/next/scripts).
+
+**TanStack Start**
+
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader from the
+[TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart):
+
+```tsx title="src/routes/__root.tsx"
+import { scripts } from '../consent-scripts';
+
+<ConsentRoot state={consent} scripts={scripts}>
+```
+
+Import vendor helpers in the root route module, not in a server function.
+A server function's return value must be serializable, and script
+configurations carry callbacks. See
+[TanStack Start scripts](https://c15t.com/docs/frameworks/tanstack-start/scripts).
+
+**React**
+
+Add the configuration to the existing `ConsentProvider` options, next to
+`mode`:
+
+```tsx title="src/consent.tsx"
+import { scripts } from './consent-scripts';
+
+<ConsentProvider options={{ mode, scripts }}>
+```
+
+`mode` is the `manifest()` value from the
+[React quickstart](../frameworks/react/quickstart.md). Keep the banner,
+dialog and preferences link inside the provider. See
+[React scripts and embeds](../frameworks/react/scripts.md).
+
+**Nuxt**
+
+Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
+relative import to where you created `consent-scripts.ts`:
+
+```ts title="app/app.config.ts"
+import { scripts } from '../src/consent-scripts';
+
+export default defineAppConfig({
+  c15t: { scripts },
+});
+```
+
+The Nuxt module merges this over its options in `nuxt.config.ts` and starts
+one script loader in the browser after hydration, once it has applied the
+visitor's stored choice and privacy signals. Keep `scripts` out of
+`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
+callbacks. Write the vendor IDs into `consent-scripts.ts`. See
+[Nuxt scripts and embeds](https://c15t.com/docs/frameworks/nuxt/scripts).
+
+**Vue**
+
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
+
+```ts title="src/main.ts"
+import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
+import { scripts } from './consent-scripts';
+
+app.use(c15tVue, {
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep your existing `mode` and other options. The plugin starts one
+script loader when the app mounts, after it has applied the visitor's stored
+choice. Do not also call `createScriptLoader` from a component. See
+[Vue scripts and embeds](https://c15t.com/docs/frameworks/vue/scripts).
+
+**Astro**
+
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
+which the integration finds on its own. Keep `astro.config.mjs` as it is.
+If the module already exports scripts, combine the two arrays.
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+Vendor helpers contain callbacks, and the integration options in
+`astro.config.mjs` are serialized into the page, so do not put helpers in
+the integration's `scripts` option. The integration passes the client
+entrypoint to the one runtime every page shares, including across
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentProvider, manifest } from 'c15t/svelte';
+  import { scripts } from './consent-scripts';
+</script>
+
+<ConsentProvider mode={manifest()} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
+handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentRoot } from 'c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+</script>
+
+<ConsentRoot state={data.consent} {scripts}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentRoot>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`:
+a server load cannot send functions to the browser. Prerendered, static and
+SPA-mode pages use the same `scripts` prop. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**HTML**
+
+The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
+page that loads the c15t script tag, paste the vendor's own snippet instead
+and keep it inert until its category is allowed:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+```
+
+Use the category this guide names for the vendor. c15t runs the snippet
+once that category is allowed, and reloads the page when the visitor
+withdraws it. Helper options on this page, such as `loadMode`, do not apply
+to a pasted snippet. See [HTML scripts](https://c15t.com/docs/frameworks/html/scripts).
+
+**JavaScript**
+
+Pass the scripts to `init()` from `@c15t/browser`, next to your mode:
+
+```ts
+import { init, manifest } from '@c15t/browser';
+import { scripts } from './consent-scripts';
+
+const consent = init({
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep the mode from your quickstart. With
+`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
+A kernel you create yourself needs a loader from
+`c15t/modules/script-loader`. Attach one loader per kernel. See
+[JavaScript scripts](https://c15t.com/docs/frameworks/javascript/scripts).
+
+## Options
+
+| Option      | Default                                        | Behavior                                                                                                                                                                                                                  |
+| ----------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `projectId` | Required                                       | Public project number as a string or safe integer. Surrounding whitespace is trimmed. Use a string above `Number.MAX_SAFE_INTEGER`. Missing, blank, nonnumeric or unsafe numeric values log an error and skip the loader. |
+| `category`  | `'experience'`                                 | Consent category or condition required before loading, such as `'measurement'` or `{ and: ['experience', 'measurement'] }`.                                                                                               |
+| `scriptSrc` | `https://cdn.optimizely.com/js/<projectId>.js` | Custom snippet or proxy URL. The project ID is still required. A blank override uses the default. This doesn't proxy the SDK's other requests.                                                                            |
+| `nonce`     | None                                           | CSP nonce for the loader element. Surrounding whitespace is trimmed. You can also supply the nonce through your consent provider.                                                                                         |
+
+Optimizely leaves cookie classification to the site owner. The helper uses
+`experience` because the snippet changes and tests user experiences. If your
+policy also requires measurement consent, pass both categories in an `and`
+condition.
+
+## Loading and revocation
+
+### Page flicker
+
+After consent, c15t inserts the loader into `<head>` with `async: false`.
+Optimizely activates the configured experiments when the snippet runs. The
+helper doesn't call `sendEvents`, start a second SDK or replace an existing
+`window.optimizely`.
+
+Optimizely recommends a synchronous snippet near the start of `<head>` and
+warns against loading it through a tag manager. A script inserted at runtime
+with `async: false` doesn't block the HTML parser. While c15t waits for
+consent, visitors can see the original page before Optimizely applies a
+variation. Plan your experiments for this flicker and for visitors who don't
+grant consent.
+
+The helper has no early-load or event-holding mode. Optimizely's `holdEvents`
+API holds event delivery, but the SDK still runs and queues events in
+localStorage. `sendEvents` releases those queued events, including events
+stored on earlier pages. Loading the snippet early would break this helper's
+consent gate.
+
+### Revocation
+
+Keep your provider's `reloadOnConsentRevoked` enabled. When a visitor revokes
+the mapped category or turns off the Optimizely vendor, c15t removes the
+loader and reloads the page after pending saves settle. The new page keeps the
+snippet blocked until consent is granted again.
+
+The standalone core `createScriptLoader` removes script elements but doesn't
+reload the page. If you use it directly, your app must persist the denied
+choice and reload. Permission changes caused by expiry or policy updates also
+don't trigger the provider's visitor-action reload.
+
+Removing the loader doesn't unload the running SDK, undo its page changes or
+delete its cookies and localStorage. A browser can also finish running an
+in-flight script after its element is removed. Optimizely can keep running
+until the page unloads, including while c15t waits for a save to finish. The
+reload ends it in the current document. If you turn reloads off, the helper
+can't make Optimizely stop tracking or changing the page after revocation.
+
+Optimizely documents `disable` for calls made before the snippet loads. It
+isn't a documented way to stop a snippet that is already running.
+`holdEvents` also leaves local collection active, so it isn't a full stop API.
+
+## Persistent Optimizely opt-out
+
+For a deliberate persistent opt-out, import `optOutOptimizely` from
+`@c15t/integrations/optimizely` and call `optOutOptimizely()`. It sends
+`window.optimizely.push({ type: 'optOut', isOptOut: true })` through an
+existing SDK or queue, and does nothing if neither exists.
+
+Optimizely records this choice in the ten-year `optimizelyOptOut` cookie.
+Granting consent again in c15t doesn't clear that cookie, so the helper never
+calls this utility on ordinary revocation. The command returns no completion
+promise and doesn't undo changes already applied to the page. Keep the page
+reload enabled when you use it.
+
+To reverse an explicit opt-out after the visitor grants consent, follow
+Optimizely's [cookie implementation guidance](https://support.optimizely.com/hc/en-us/articles/22060116282509-Cookie-implementation-options):
+delete `optimizelyOptOut` or set its value to `false`, using the cookie's
+existing domain and path, then reload or navigate to another page. On that
+page, c15t must allow the snippet to load. Optimizely's API reference warns
+that an opt-in command alone can't restart a snippet blocked by the opt-out
+cookie. Your app must reset the cookie; `optimizelyWeb` and `optOutOptimizely`
+don't.
+
+## Cookies and localStorage
+
+Optimizely's [storage reference](https://docs.optimizely.com/web-experimentation/docs/cookies-and-localstorage-in-snippets)
+lists these first-party cookies. Browser policies can shorten their lifetimes.
+
+| Cookie                       | Documented lifetime                          | Purpose                                                                  |
+| ---------------------------- | -------------------------------------------- | ------------------------------------------------------------------------ |
+| `optimizelyEndUserId`        | Six months from the last visit, configurable | Visitor identifier.                                                      |
+| `optimizelySession`          | Six months                                   | New or returning session detection.                                      |
+| `optimizelyRedirectData`     | Five seconds                                 | Data passed across redirect experiments.                                 |
+| `optimizelyDomainTestCookie` | Removed right after a successful test        | Domain detection.                                                        |
+| `optimizelyOptOut`           | Ten years                                    | Persistent Optimizely opt-out. The helper sets no opt-out cookie itself. |
+
+The SDK stores events, experiment assignments, visitor profiles and pending
+requests under localStorage keys that start with `optimizely_data$$`. The full
+key includes the visitor ID and the project or account namespace, followed by
+a name such as `events`, `event_queue`, `variation_map`, `session_state`,
+`visitor_profile`, `layer_states`, `layer_map`, `tracker_optimizely`,
+`pending_events` or `contextual_mab`.
+
+Cross-origin tracking can use origin-specific prefixes and sync through an
+account-specific `cdn.optimizely.com` origin. Edge Delivery can add
+`OPTY$$...$$VPROF` and `OPTY$$...$$VMAP` cookies with six-month lifetimes.
+Sampled Real User Monitoring uses session cookies on `rum.optimizely.com`,
+including `AWSELB`, `AWSELBCORS` and `optimizelyRumLB`. This helper loads the
+browser snippet. It doesn't configure an Edge Delivery worker.
+
+A reload keeps existing storage. Use your framework's clear-on-revocation
+configuration to remove the storage your site uses. Check the actual names and
+domains in DevTools. Cleanup on your origin can't clear cookies or
+localStorage on an Optimizely-owned origin. Optimizely warns that cookie and
+localStorage formats can change, so don't read them as an app API.
+
+## Verify Optimizely
+
+Use your own test project. With consent denied in a clean browser profile,
+filter Network by `optimizely.com` and check that the snippet doesn't load.
+The `optimizely` global, Optimizely cookies and localStorage keys should be
+absent.
+
+Grant the mapped consent and check for the project `.js` request. After a
+valid snippet runs, `window.optimizely.get` is a function. That shows an SDK
+API exists, not that a particular experiment activated or an event was
+accepted. Check experiment targeting and behavior in your test project. Deny
+the vendor inside an allowed category and confirm that the reload blocks its
+snippet too. Grant again to confirm that ordinary revocation hasn't created a
+persistent opt-out. If you use `optOutOptimizely`, also test the cookie reset
+and reload described above before you expect a later grant to resume
+experiments.
+
+Sources:
+[implement the one-line snippet](https://docs.optimizely.com/web-experimentation/docs/implement-the-one-line-javascript-snippet),
+[hold and send event timing](https://docs.optimizely.com/web-experimentation/docs/control-the-timing-of-optimizely-web-experimentation-event-dispatch-with-holdevents-and-sendevents),
+[disable API](https://docs.optimizely.com/web-experimentation/api/Ops8-disable)
+and
+[persistent opt-out API](https://docs.optimizely.com/web-experimentation/api/d8Gy-opt-out).
+
+Test in a private window with an opt-in policy. Open DevTools Network, disable
+the cache and filter by the vendor's domain:
+
+1. Load the page. No request goes to the vendor before you choose.
+2. Click Reject, then reload. There is still no vendor request.
+3. Open Privacy settings and allow the helper's category. The vendor script
+   loads without a page reload.
+4. Turn the category off again and save. c15t reloads the page, and the new
+   page makes no vendor request.
+
+c15t reloads on revocation because removing a script element does not stop
+code that already ran. The vendor's listeners, timers and queued events stay
+alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
+the vendor yourself. Register a callback-only script whose `onConsentChange`
+calls the vendor's opt-out API, as shown in
+[custom integrations](./building-integrations.md), and check the
+permission before each of your own event calls. The reload does not delete
+cookies the vendor already set; see
+[clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+The helper lists its vendor by name in the preference dialog, so a visitor can
+turn it off inside an allowed category. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup). The
+[consent verification guide](../guides/verify-consent.md) covers navigation,
+expiry and hosting checks.