@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/rudderstack.md

@@ -1,271 +1,328 @@
 ---
 title: RudderStack
-description: Load RudderStack's JavaScript SDK with c15t and gate the browser
-  SDK behind measurement consent.
+description: Gate the RudderStack browser SDK or map c15t categories to
+  destination consent IDs.
 group: integrations
-icon: rudderstack
 ---
-[RudderStack](https://www.rudderstack.com/) collects customer data from websites and routes it through your RudderStack data plane to downstream destinations. The `rudderstack()` helper creates RudderStack's `window.rudderanalytics` v3 queue, queues the required `load()` call with your write key and data plane URL, optionally queues the initial `page()` call, and loads the browser SDK when `measurement` consent is available.
 
-## Integrate with c15t
+## Configure RudderStack
 
-**React**
+Copy the source write key and HTTPS data plane URL from your RudderStack source.
+The default helper waits for measurement permission before loading the SDK.
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
+
+```ts title="src/consent-scripts.ts"
 import { rudderstack } from '@c15t/scripts/rudderstack';
 
-const scripts = [
+export const scripts = [
   rudderstack({
-    writeKey: 'WRITE_KEY',
-    dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
+    writeKey: 'YOUR_SOURCE_WRITE_KEY',
+    dataPlaneUrl: 'https://your-data-plane.example.com',
   }),
 ];
-
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
 ```
 
-**Next.js**
+Replace both values before running the example. Keep secret control-plane
+credentials out of the browser.
 
-```tsx
-'use client';
+## Register the scripts
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { rudderstack } from '@c15t/scripts/rudderstack';
+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 c15t owns loading once.
 
-const scripts = [
-  rudderstack({
-    writeKey: 'WRITE_KEY',
-    dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-  }),
-];
+The `scripts` export in `src/consent-scripts.ts` is a configuration, not an
+initializer. Add it to your existing consent owner using the registration point
+below. These are partial edits to that owner, not additional providers.
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
-```
+**Next.js**
 
-**JavaScript**
+Import the configuration into the client boundary from your router guide:
 
 ```ts
-import { getOrCreateConsentRuntime } from 'c15t';
-import { rudderstack } from '@c15t/scripts/rudderstack';
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    rudderstack({
-      writeKey: 'WRITE_KEY',
-      dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-    }),
-  ],
-});
+Keep the server-resolved `state` and shared `consentConfig` from your
+router guide. Its manifest, init and save URLs stay in effect. Add
+`scripts` as a top-level prop on the existing root:
+
+```tsx
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
 ```
 
-## How c15t loads it
+For a Pages Router or static-export setup using `ConsentProvider`, add
+`scripts` to its existing `options` instead. Keep the router-specific setup
+from [Next.js script loading](../frameworks/next/script-loader.md).
 
-* **Category:** `measurement` (Analytics)
-* **Loads when:** measurement consent is granted
-* **On revocation:** unloaded - c15t removes the script element from the DOM and clears RudderStack globals until consent is granted again.
+**TanStack Start**
 
-The helper maps RudderStack's v3 browser snippet into the manifest engine:
+In your existing root route component, import the scripts alongside
+`ConsentRoot`. Keep the server loader from the [TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart).
 
-```ts
-rudderstack({
-  writeKey: 'WRITE_KEY',
-  dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-});
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
+
+function Root() {
+  const state = Route.useLoaderData();
+  return (
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
+  );
+}
 ```
 
-It creates `window.rudderanalytics`, defines the v3 snippet queue methods, queues:
+This edits the existing route. `Route` and `backendURL` come from its setup;
+keep the document shell and head components if they are part of your root.
+`initRoute={false}` keeps the quickstart's direct-backend initialization.
+If your app mounts a consent server route, retain its existing `initRoute`
+instead. Do not return script callbacks from a server function or route loader.
+
+**React**
+
+Import the scripts into your existing provider component:
 
 ```ts
-window.rudderanalytics.load(
-  'WRITE_KEY',
-  'https://example.dataplane.rudderstack.com',
-  {}
-);
-window.rudderanalytics.page();
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
 ```
 
-and loads:
+Keep the existing options and add `scripts`:
 
-```txt
-https://cdn.rudderlabs.com/v3/modern/rsa.min.js
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
 ```
 
-`writeKey` and `dataPlaneUrl` are both required and must be non-empty strings after trimming. `dataPlaneUrl` must be a valid HTTPS URL.
+Here `consentOptions` is your existing configuration, including
+`mode: hosted({ url: backendURL })`. Keep the banner, dialog and preferences
+link inside the provider. See [React script loading](../frameworks/react/script-loader.md).
 
-## Configure load options
+**Nuxt**
 
-Pass `loadOptions` to provide RudderStack SDK options as the third `load()` argument. Values must be JSON-serializable: plain objects, arrays, strings, numbers, booleans, and `null`.
+Attach one loader from the root `app.vue`, after the Nuxt module has
+started its browser runtime. This keeps vendor callbacks in application code rather
+than serialized `nuxt.config.ts` runtime configuration.
 
-```ts
-import { rudderstack } from '@c15t/scripts/rudderstack';
+```vue title="app/app.vue"
+<script setup lang="ts">
+import { onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from '../src/consent-scripts';
+
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-rudderstack({
-  writeKey: 'WRITE_KEY',
-  dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-  loadOptions: {
-    useBeacon: true,
-    plugins: ['BeaconQueue'],
-  },
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
 });
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
+});
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-Do not pass functions, Dates, Maps, Sets, class instances, symbols, or other non-JSON values in `loadOptions`.
+Merge the setup code into your root and retain its footer and preferences
+link. `useConsentKernel` is auto-imported by the c15t Nuxt module. Adjust the
+relative script import if your `app.vue` is at the project root. This loader
+waits until the module has applied browser persistence and privacy signals,
+then reads the current snapshot and observes future changes. Do not also register these scripts
+in another loader. See the [Nuxt quickstart](https://c15t.com/docs/frameworks/nuxt/quickstart).
 
-## Configure page tracking
+**Vue**
 
-By default the helper queues `rudderanalytics.page()` before the vendor bundle loads. If you want to handle page views yourself, set `trackPageView` to `false`.
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
 
-```ts
-rudderstack({
-  writeKey: 'WRITE_KEY',
-  dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-  trackPageView: false,
-});
-```
+```vue title="src/App.vue"
+<script setup lang="ts">
+import { onMounted, onUnmounted } from 'vue';
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { useConsentKernel } from 'c15t/vue/vue-plugin';
+import ConsentRoot from 'c15t/vue/consent-root';
+import { scripts } from './consent-scripts';
 
-To proxy or self-host the loader, pass a custom URL:
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-```ts
-rudderstack({
-  writeKey: 'WRITE_KEY',
-  dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-  scriptUrl: 'https://analytics.example.com/rsa.min.js',
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
 });
-```
-
-## Consent behavior
-
-RudderStack exposes a `consent()` API for its own consent-management flow and pre-consent event handling. That API is not a simple runtime opt-out or revocation API for c15t to call after a user withdraws `measurement` consent.
+onUnmounted(() => loader?.dispose());
+</script>
 
-c15t therefore uses the post-consent model recommended by RudderStack's docs: it does not load the SDK until `measurement` consent is granted, and it unloads the script if that consent is later revoked.
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
+```
 
-### Why c15t blocks the load instead of mapping consent into RudderStack
+Keep your existing page content and preferences link. The plugin still owns
+the kernel and persistence; this component owns only the vendor loader.
+Do not register the same scripts in plugin configuration as well. See the
+[Vue quickstart](https://c15t.com/docs/frameworks/vue/quickstart).
 
-Some integrations — Google Tag Manager is the clearest example — load immediately and receive c15t's consent state through the vendor's own consent API (Google Consent Mode v2). That model is only safe when the vendor API provides denied-by-default semantics where **nothing identifying is stored or transmitted before consent**.
+**Astro**
 
-Loading the RudderStack SDK does not provide that guarantee on its own: once loaded normally it writes its `anonymousId` cookie and delivers events to your data plane, and the `consent()` API filters which downstream *destinations* receive those events rather than preventing collection. Even RudderStack's pre-consent mode defaults to `events.delivery: 'immediate'`, which still sends pre-decision events. "Loaded but consent-filtered" is still collection, so c15t treats blocking the load as the only default that reliably honors a missing or denied `measurement` consent.
+Point the existing Astro integration at a client module. Keep its `mode`,
+`ui` and framework integration from the [Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart).
+Import `fileURLToPath` in your Astro configuration:
 
-RudderStack v3 does offer a pre-consent mode (`preConsent` load options with storage disabled and buffered delivery) designed for CMP integrations, which allows a GTM-style flow. c15t supports it as an explicit opt-in — see below. It is not the default because it runs vendor code before consent and depends on vendor-side configuration (consent IDs on every destination) that c15t cannot verify from the browser.
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
+```
 
-The same reasoning applies to the other customer-data-platform helpers (Segment, Hightouch): their consent surfaces are destination filters, not collection gates, so those helpers block the load too.
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-### Opt-in: pre-consent mode with consent ID mapping
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
 
-Pass `consentManagement` to make c15t the consent provider for RudderStack's pre-consent flow:
+Export the scripts from that module:
 
-```ts
-import { rudderstack } from '@c15t/scripts/rudderstack';
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
 
-rudderstack({
-  writeKey: 'WRITE_KEY',
-  dataPlaneUrl: 'https://example.dataplane.rudderstack.com',
-  consentManagement: {
-    // c15t category → RudderStack consent IDs (from your destination settings)
-    mapping: {
-      measurement: ['product-analytics'],
-      marketing: ['ad-destinations'],
-    },
-  },
-});
+export default { scripts } satisfies C15tClientOptionsExtension;
 ```
 
-In this mode:
+The integration passes this extension to its shared browser runtime. Vendor
+helpers contain callbacks, so do not put them in the serialized `scripts`
+option in `astro.config.mjs`. Keep one runtime across consent islands and
+`ClientRouter` navigation.
 
-* The SDK loads immediately for every visitor, but **inert**: `preConsent` is enabled with storage strategy `none` (no cookies, no localStorage) and buffered event delivery — nothing reaches your data plane before a consent decision.
-* On every consent decision and change, c15t calls `rudderanalytics.consent()` with `allowedConsentIds`/`deniedConsentIds` partitioned from your mapping. The initial signal is queued before the SDK loads, so consent state is known the moment the SDK initializes.
-* Consent revocation re-signals with the denied IDs instead of unloading the script.
+**Svelte**
 
-**Event attribution.** This is the reason to opt in: events fired before the user interacts with the consent banner (the initial `page()` call, early product events) are buffered and delivered once consent is granted, so consenting users keep their full journey. In the default blocked-load mode those pre-consent events are simply lost. If you want session stitching across the consent boundary as well, pass your own `preConsent` in `loadOptions` with storage strategy `'session'` — c15t keeps your storage choice but always forces `preConsent.enabled`, buffered event delivery, and the `custom` consent provider, since any of those falling back to SDK defaults would leak pre-consent events.
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
 
-**Requirements and caveats:**
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
 
-* Every destination in your RudderStack workspace must be assigned the consent IDs used in the mapping. Destinations without consent IDs receive events regardless of consent — that is RudderStack behavior c15t cannot detect or prevent from the browser.
-* Users who never consent have their buffered events discarded; nothing is persisted for them.
-* The daily [script vendor monitor](https://github.com/c15t/c15t/issues/899) probes this mode against the live SDK: it loads RudderStack with denied consent in a real browser and asserts zero data plane requests and zero `rl_*` storage, so a vendor-side change to pre-consent semantics is caught automatically.
+  const backendURL = import.meta.env.VITE_C15T_BACKEND_URL;
+  if (!backendURL) throw new Error('Set VITE_C15T_BACKEND_URL');
+  const mode = hosted({ url: backendURL });
+</script>
 
-### Choosing a consent model for CDPs
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
 
-* **Default (blocked load)** — strictest interpretation of consent; no vendor code runs pre-consent. Pre-consent events are lost. Right when compliance posture outweighs attribution.
-* **Pre-consent mode (`consentManagement`)** — vendor-sanctioned CMP flow; pre-consent events are buffered and attributed for consenting users. Requires disciplined destination consent-ID configuration and accepts vendor code running before consent, with the live monitor verifying its inertness daily.
+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.
 
-## Tracking events in your app
+**SvelteKit**
 
-c15t gates the RudderStack browser SDK from loading until `measurement` consent is granted. Your application code that calls RudderStack's runtime API (`window.rudderanalytics.track`, `identify`, etc.) is **not** automatically gated - `window.rudderanalytics` does not exist until the script is loaded, so unguarded calls before consent throw.
+Add the scripts to the existing root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
 
-Guard event calls by checking consent state. From React:
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
 
-```tsx
-import { useCallback } from 'react';
-import { useConsentManager } from '@c15t/react';
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
 
-function SignupExample() {
-  const { has } = useConsentManager();
-
-  const trackSignup = useCallback(() => {
-    if (has('measurement')) {
-      window.rudderanalytics?.track('Signup Completed', { plan: 'pro' });
-    }
-  }, [has]);
-}
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-From plain JavaScript:
+Import vendor helpers in the layout component, not in `+layout.server.ts`.
+For static hosting, keep your browser-only `mode` setup and omit request
+prefetch; the `scripts` prop stays the same. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
 
-```ts
-import { getOrCreateConsentRuntime } from 'c15t';
+**JavaScript**
 
-const { consentStore } = getOrCreateConsentRuntime();
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
 
-if (consentStore.getState().has('measurement')) {
-  window.rudderanalytics?.track('Signup Completed', { plan: 'pro' });
-}
-```
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
 
-## Types
+const loader = createScriptLoader({ kernel, scripts });
+```
 
-### RudderStackOptions
+Call `loader.dispose()` when that application instance is destroyed.
+`kernel` is the hosted kernel from your quickstart. A provider-owned kernel
+already has a loader; do not attach a second one. See
+[JavaScript script loading](../frameworks/javascript/script-loader.md).
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`RudderStackOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/analytics/rudderstack.ts\`|
+## Map destination consent when loading before permission
 
-\*ExtractedTypeTable: Could not extract "RudderStackOptions" from "./packages/scripts/src/vendors/analytics/rudderstack.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+`consentManagement` changes the loading contract. The SDK loads immediately,
+receives pre-consent configuration, and stays loaded after revocation. c15t
+sends consent updates through `rudderanalytics.consent()`.
 
-### Script
+```ts title="src/consent-scripts.ts"
+import { rudderstack } from '@c15t/scripts/rudderstack';
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+export const scripts = [
+  rudderstack({
+    writeKey: 'YOUR_SOURCE_WRITE_KEY',
+    dataPlaneUrl: 'https://your-data-plane.example.com',
+    consentManagement: {
+      mapping: {
+        measurement: ['product-analytics'],
+        marketing: ['advertising'],
+      },
+    },
+  }),
+];
+```
 
-\*ExtractedTypeTable: Could not extract "Script" from "./packages/core/src/libs/script-loader/types.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+The IDs in this example are placeholders for your destination consent settings.
+Allowed c15t categories contribute their IDs to `allowedConsentIds`; denied
+categories contribute theirs to `deniedConsentIds`. Test each destination
+independently. This mode does not prevent the initial SDK request.
+
+## Options
+
+| Option                      | Behavior                                                                      |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `writeKey`                  | Required non-empty browser source key.                                        |
+| `dataPlaneUrl`              | Required HTTPS data plane URL.                                                |
+| `consentManagement.mapping` | Optional category-to-consent-ID map. Enables pre-consent loading.             |
+| `loadOptions`               | Optional JSON-serializable SDK options; functions are not supported.          |
+| `trackPageView`             | Defaults to `true`, queuing an initial `page()` call.                         |
+| `scriptUrl`                 | Optional HTTPS loader override. Defaults to the modern v3 RudderStack loader. |
+
+## Verify the integration
+
+In the default mode, confirm denial prevents the initial SDK load. With a
+consent mapping, expect the SDK request and inspect the destination consent IDs
+instead. The default mode has no vendor shutdown hook after loading, so verify
+revocation beyond script removal. In both modes, check routing for duplicate
+page events and stop disallowed application events. See
+[consent verification](../guides/verify-consent.md).