@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/reddit-pixel.md

@@ -1,241 +1,294 @@
 ---
 title: Reddit Pixel
-description: Track conversions and build retargeting audiences for Reddit
-  advertising campaigns.
+description: Configure Reddit Pixel with c15t v3, understand marketing
+  permission and verify loading and revocation.
 group: integrations
-icon: reddit
 ---
-Reddit Pixel is Reddit's conversion tracking tool for ads and remarketing. It seeds the standard `rdt` queue before the vendor bundle loads, initializes your pixel, and by default records a `PageVisit` event once consent for `marketing` is available.
 
-## Integrate with c15t
+## Configure Reddit Pixel
 
-**React**
+Use your Reddit Pixel ID. The helper initializes `rdt` and queues `PageVisit` by default.
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { redditPixel } from '@c15t/scripts/reddit-pixel';
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-const scripts = [redditPixel({ pixelId: 't2_abcdef' })];
+```ts title="src/consent-scripts.ts"
+import { redditPixel } from '@c15t/scripts/reddit-pixel';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const scripts = [redditPixel({ pixelId: 't2_YOUR_PIXEL_ID' })];
 ```
 
+## 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 c15t owns loading once.
+
+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.
+
 **Next.js**
 
+Import the configuration into the client boundary from your router guide:
+
+```ts
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
+```
+
+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
-'use client';
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { redditPixel } from '@c15t/scripts/reddit-pixel';
+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).
+
+**TanStack Start**
+
+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).
 
-const scripts = [redditPixel({ pixelId: 't2_abcdef' })];
+```tsx
+import { Outlet } from '@tanstack/react-router';
+import { ConsentRoot } from 'c15t/tanstack-start';
+import { scripts } from '../consent-scripts';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
+function Root() {
+  const state = Route.useLoaderData();
   return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: '/api/c15t',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
+    <ConsentRoot state={state} backendURL={backendURL} initRoute={false} scripts={scripts}>
+      <Outlet />
+      {/* Keep your consent banner, dialog and preferences link here. */}
+    </ConsentRoot>
   );
 }
 ```
 
-**JavaScript**
+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
-import { getOrCreateConsentRuntime } from 'c15t';
-import { redditPixel } from '@c15t/scripts/reddit-pixel';
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [redditPixel({ pixelId: 't2_abcdef' })],
-});
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
 ```
 
-## How c15t loads it
+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).
 
-* **Category:** `marketing` (Ads & Pixels)
-* **Loads when:** marketing consent is granted
-* **On revocation:** retained in the DOM so c15t can call Reddit's
-  first-party-cookie controls. c15t calls `rdt('disableFirstPartyCookies')`
-  when marketing consent is denied and `rdt('enableFirstPartyCookies')` when
-  it is granted again.
+**Nuxt**
 
-If you prefer to control page-view tracking yourself, disable the default `PageVisit` call:
+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
-redditPixel({
-  pixelId: 't2_abcdef',
-  trackPageVisit: false,
-})
+```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;
+
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
+});
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-## Tracking events in your app
+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).
 
-c15t gates the Reddit Pixel script from loading until `marketing` consent is granted. Your application code that calls Reddit's runtime API (`window.rdt(...)`) is **not** automatically gated - `window.rdt` does not exist until the script is loaded, so unguarded calls before consent throw.
+**Vue**
 
-Guard event calls by checking consent state. From React:
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
 
-```tsx
-import { useCallback } from 'react';
-import { useConsentManager } from '@c15t/react';
-import { redditPixelEvent } from '@c15t/scripts/reddit-pixel';
-
-function CheckoutExample() {
-  const { has } = useConsentManager();
-
-  const trackPurchase = useCallback(() => {
-    if (has('marketing')) {
-      redditPixelEvent('Purchase', {
-        currency: 'USD',
-        value: 99,
-        conversionId: 'order-123',
-      });
-    }
-  }, [has]);
-
-  // Call trackPurchase() from your conversion success path.
-}
+```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';
+
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
+
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
 ```
 
-From plain JavaScript:
+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).
 
-```ts
-import { getOrCreateConsentRuntime } from 'c15t';
+**Astro**
 
-const { consentStore } = getOrCreateConsentRuntime();
+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:
 
-if (consentStore.getState().has('marketing')) {
-  window.rdt?.('track', 'Purchase', {
-    currency: 'USD',
-    value: 99,
-    conversionId: 'order-123',
-  });
-}
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
 ```
 
-When you use Reddit Pixel and Conversions API together, send the same
-`conversionId` in the browser event and the server event so Reddit can
-deduplicate them.
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-## Consent and privacy
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
 
-c15t keeps Reddit Pixel behind `marketing` consent. Before marketing consent,
-the Reddit script is not loaded. After marketing consent is granted, c15t loads
-the script and queues the Reddit `init` call.
+Export the scripts from that module:
 
-For stricter first-party-cookie behavior, disable Reddit first-party cookies
-during initialization:
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
 
-```ts
-redditPixel({
-  pixelId: 't2_abcdef',
-  disableFirstPartyCookies: true,
-})
+export default { scripts } satisfies C15tClientOptionsExtension;
 ```
 
-You can also pass Reddit's initialization options directly:
+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.
 
-```ts
-redditPixel({
-  pixelId: 't2_abcdef',
-  initOptions: {
-    optOut: true,
-    disableFirstPartyCookies: true,
-  },
-})
-```
+**Svelte**
 
-Reddit supports a Limited Data Use flag through data processing fields. Use the
-values required by your policy and jurisdiction:
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
 
-```ts
-redditPixel({
-  pixelId: 't2_abcdef',
-  initOptions: {
-    dpm: ['LDU'],
-    dpcc: 'US',
-    dprc: 'CA',
-  },
-})
-```
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
 
-Reddit can also receive attribution matching signals such as `email`,
-`phoneNumber`, `externalId`, `aaid`, and `idfa`. Only pass those fields after
-you have the right consent or legal basis for your use case:
+  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>
 
-```ts
-redditPixel({
-  pixelId: 't2_abcdef',
-  initOptions: {
-    email: 'person@example.com',
-    externalId: 'customer-123',
-    aam: {
-      email: false,
-      phone_number: false,
-    },
-  },
-})
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-See Reddit's docs for [Limited Data Use](https://business.reddithelp.com/s/article/Limited-Data-Use),
-[event metadata](https://business.reddithelp.com/s/article/about-event-metadata),
-and [event deduplication](https://business.reddithelp.com/s/article/event-deduplication).
+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 root layout provider. Keep the server load
+and its serializable prefetch data from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
 
-## Types
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
 
-### RedditPixelOptions
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`RedditPixelOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/reddit-pixel.ts\`|
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+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.
+
+**JavaScript**
 
-\*ExtractedTypeTable: Could not extract "RedditPixelOptions" from "./packages/scripts/src/vendors/ads-and-pixels/reddit-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
 
-### RedditPixelInitOptions
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
+```
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`RedditPixelInitOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/reddit-pixel.ts\`|
+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).
 
-\*ExtractedTypeTable: Could not extract "RedditPixelInitOptions" from "./packages/scripts/src/vendors/ads-and-pixels/reddit-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+## Options
 
-### RedditPixelEventMetadata
+| Option                     | Behavior                                                 |
+| -------------------------- | -------------------------------------------------------- |
+| `pixelId`                  | Required Reddit Pixel ID.                                |
+| `trackPageVisit`           | Defaults to `true`.                                      |
+| `initOptions`              | Optional Reddit initialization and matching settings.    |
+| `disableFirstPartyCookies` | Merged into the initialization options when supplied.    |
+| `scriptUrl`                | Defaults to `https://www.redditstatic.com/ads/pixel.js`. |
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`RedditPixelEventMetadata\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/reddit-pixel.ts\`|
+## Consent behavior
 
-\*ExtractedTypeTable: Could not extract "RedditPixelEventMetadata" from "./packages/scripts/src/vendors/ads-and-pixels/reddit-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+The first load waits for marketing permission. The helper retains the pixel after revocation and calls `disableFirstPartyCookies`; a later grant calls `enableFirstPartyCookies`. Disabling cookies does not stop all events. `redditPixelEvent` checks API availability, not consent.
 
-### Script
+## Verify the integration
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Inspect the initial PageVisit and verify cookie commands on revocation. Stop application conversion calls when marketing is denied, even if `rdt` remains callable.
 
-\*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.\*
+Use a fresh session with an opt-in policy to check initial denial. Then grant
+`marketing`, revoke it, and reload. Inspect both network requests and future
+application events. Removing a script cannot undo code or requests that already
+ran. Follow the [consent verification guide](../guides/verify-consent.md).