@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/meta-pixel.md

@@ -1,412 +1,285 @@
 ---
 title: Meta Pixel
-description: Track conversions and build audiences for Facebook and Instagram
-  advertising campaigns.
-icon: meta
+description: Register the Meta Pixel under marketing permission and verify event
+  calls after revocation.
 group: integrations
 ---
-Meta Pixel (formerly Facebook Pixel) is Meta's conversion tracking and audience targeting tool for Facebook and Instagram advertising. It tracks user actions, measures ad effectiveness, builds custom audiences, and optimizes ad delivery.
 
-## Integrate with c15t
+## Register the pixel
 
-**React**
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
+```ts title="src/consent-scripts.ts"
 import { metaPixel } from '@c15t/scripts/meta-pixel';
 
-const scripts = [
-  metaPixel({
-    pixelId: '123456789012345',
-  }),
-];
-
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const scripts = [metaPixel({ pixelId: '123456789012345' })];
 ```
 
-**Next.js**
+Replace the pixel ID and pass `scripts` to your existing provider or core script
+loader. The helper uses the `marketing` category. Remove the original pixel
+snippet, including a separately installed tracking image or tag-manager entry.
 
-```tsx
-'use client';
+## Register the scripts
 
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/nextjs';
-import { metaPixel } from '@c15t/scripts/meta-pixel';
+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 = [
-  metaPixel({
-    pixelId: '123456789012345',
-  }),
-];
+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 { metaPixel } from '@c15t/scripts/meta-pixel';
-
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    metaPixel({
-      pixelId: '123456789012345',
-    }),
-  ],
-});
+import { ConsentRoot } from 'c15t/next';
+import { scripts } from './consent-scripts';
 ```
 
-## How c15t loads it
+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:
 
-* **Category:** `marketing` (Ads & Pixels)
-* **Loads when:** marketing consent is granted
-* **Default install:** c15t queues `fbq('consent', 'grant')`, `fbq('init', pixelId)`, `fbq('track', 'PageView')`, then loads Meta's `fbevents.js`
-* **On revocation:** [persists](/docs/frameworks/react/script-loader#persist-after-revocation) — c15t calls `fbq('consent', 'revoke')` so Meta stops tracking without removing the script
+```tsx
+<ConsentRoot state={state} config={consentConfig} scripts={scripts}>
+  {children}
+</ConsentRoot>
+```
 
-Meta recommends installing the base pixel on every page you want to measure. c15t injects scripts into the document head by default, which matches Meta's recommendation to load the pixel early.
+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).
 
-## Configure the integration
+**TanStack Start**
 
-Use the default setup when you want Meta's standard `PageView` event to fire as soon as the pixel loads after marketing consent.
+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
-metaPixel({
-  pixelId: '123456789012345',
-});
+```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>
+  );
+}
 ```
 
-For single-page applications, disable the automatic `PageView` and track route changes yourself.
+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.
 
-```ts
-metaPixel({
-  pixelId: '123456789012345',
-  trackPageView: false,
-});
-```
+**React**
 
-You can pass optional init data as the third argument to `fbq('init', ...)`.
+Import the scripts into your existing provider component:
 
 ```ts
-metaPixel({
-  pixelId: '123456789012345',
-  initOptions: {
-    external_id: 'customer-123',
-  },
-});
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
 ```
 
-## Tracking events in your app
+Keep the existing options and add `scripts`:
 
-c15t gates the Meta Pixel script from loading until `marketing` consent is
-granted. After consent is granted the script stays in the DOM, and c15t calls
-`fbq('consent', 'revoke')` if consent is later revoked so Meta stops tracking
-without removing the script.
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
 
-This means `window.fbq` and the `metaPixelEvent` helpers are only defined after
-the user has granted marketing consent at least once. Before that, unguarded
-calls throw.
+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).
 
-### Standard events
+**Nuxt**
 
-Use `metaPixelEvent` to track Meta standard events. It is a typed wrapper around `fbq('track', ...)`.
+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.
 
-Meta documents standard event tracking in its [conversion tracking guide](https://developers.facebook.com/docs/meta-pixel/implementation/conversion-tracking) and [Marketing API pixel examples](https://developers.facebook.com/docs/meta-pixel/implementation/marketing-api).
+```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';
 
-```ts
-import { metaPixelEvent } from '@c15t/scripts/meta-pixel';
+const nuxtApp = useNuxtApp();
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-metaPixelEvent('Lead', {
-  value: 40,
-  currency: 'USD',
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
 });
-
-metaPixelEvent('AddToCart', {
-  content_ids: ['SKU-123'],
-  content_type: 'product',
-  value: 49.99,
-  currency: 'USD',
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
 });
+</script>
 
-metaPixelEvent(
-  'Purchase',
-  {
-    contents: [
-      { id: 'SKU-123', quantity: 2 },
-      { id: 'SKU-456', quantity: 1 },
-    ],
-    content_type: 'product',
-    value: 149.97,
-    currency: 'USD',
-  },
-  'browser-event-123'
-);
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-The optional third argument can be an event ID string or an options object. c15t forwards string IDs as `{ eventID: '...' }`, which is the browser-side format used for Conversions API deduplication.
+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).
 
-```ts
-metaPixelEvent(
-  'Purchase',
-  { value: 149.97, currency: 'USD' },
-  { eventID: 'browser-event-123' }
-);
-```
+**Vue**
 
-### Custom events
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
 
-Use `metaPixelCustomEvent` when Meta's standard events do not fit the action you are measuring. Meta custom event names must be strings and cannot exceed 50 characters.
+```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';
 
-```ts
-import { metaPixelCustomEvent } from '@c15t/scripts/meta-pixel';
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-metaPixelCustomEvent('ShareDiscount', {
-  promotion: 'share_discount_10%',
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
 });
-```
-
-Custom events can also use an event ID for Conversions API deduplication.
+onUnmounted(() => loader?.dispose());
+</script>
 
-```ts
-metaPixelCustomEvent(
-  'ShareDiscount',
-  { promotion: 'share_discount_10%' },
-  'browser-event-456'
-);
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
 ```
 
-### Guard event calls with consent
+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).
 
-The example below intentionally uses `useConsentManager().has('marketing')` as
-a defensive policy so your app avoids calling `metaPixelEvent` whenever consent
-is currently revoked, even though Meta also suppresses tracking after initial
-load.
-
-```tsx
-import { useConsentManager } from '@c15t/react';
-import { metaPixelEvent } from '@c15t/scripts/meta-pixel';
-
-function useTrackPurchase() {
-  const { has } = useConsentManager();
-
-  // Defensive pattern: only call metaPixelEvent while marketing consent is granted.
-  return () => {
-    if (has('marketing')) {
-      metaPixelEvent('Purchase', { value: 10.0, currency: 'USD' });
-    }
-  };
-}
+**Astro**
 
-function PurchaseButton() {
-  const trackPurchase = useTrackPurchase();
+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:
 
-  return <button onClick={trackPurchase}>Complete purchase</button>;
-}
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
 ```
 
-### SPA route changes
-
-Meta's [SPA guidance](https://developers.facebook.com/docs/facebook-pixel/implementation/tag_spa) recommends tracking meaningful URL changes from your router. Disable the install-time `PageView`, then emit page views after navigation while marketing consent is granted.
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-```tsx
-import { useConsentManager } from '@c15t/react';
-import { metaPixelEvent } from '@c15t/scripts/meta-pixel';
-import { useEffect } from 'react';
-import { useLocation } from 'react-router-dom';
-
-function MetaRouteTracking() {
-  const { has } = useConsentManager();
-  const location = useLocation();
-
-  useEffect(() => {
-    if (has('marketing')) {
-      metaPixelEvent('PageView');
-    }
-  }, [has, location.pathname, location.search]);
-
-  return null;
-}
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
 ```
 
-## Consent and privacy
-
-Meta's GDPR guidance documents `fbq('consent', 'revoke')` and `fbq('consent', 'grant')`. c15t handles those calls for you after the script has loaded once:
-
-* Before marketing consent, c15t does not load Meta Pixel.
-* When marketing consent is granted, c15t loads Meta Pixel and calls `fbq('consent', 'grant')`.
-* When marketing consent is revoked later, c15t keeps the script in place and calls `fbq('consent', 'revoke')`.
-
-For US state privacy rules, Meta supports [Data Processing Options](https://developers.facebook.com/docs/meta-pixel/implementation/data-processing-options). Pass `dataProcessingOptions` to queue `fbq('dataProcessingOptions', ...)` before `fbq('init', ...)`.
-
-Let Meta geolocate Limited Data Use:
-
-```ts
-metaPixel({
-  pixelId: '123456789012345',
-  dataProcessingOptions: {
-    options: ['LDU'],
-    country: 0,
-    state: 0,
-  },
-});
-```
+Export the scripts from that module:
 
-Enable Limited Data Use for California:
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
 
-```ts
-metaPixel({
-  pixelId: '123456789012345',
-  dataProcessingOptions: {
-    options: ['LDU'],
-    country: 1,
-    state: 1000,
-  },
-});
+export default { scripts } satisfies C15tClientOptionsExtension;
 ```
 
-Explicitly disable Limited Data Use:
+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
-metaPixel({
-  pixelId: '123456789012345',
-  dataProcessingOptions: {
-    options: [],
-  },
-});
-```
-
-## Catalog and collaborative ads
+**Svelte**
 
-For Advantage+ catalog ads, Meta requires `ViewContent`, `AddToCart`, and `Purchase` events to include either `content_ids` or `contents`. IDs must match your product catalog. See Meta's [Advantage+ catalog ads guide](https://developers.facebook.com/docs/meta-pixel/get-started/advantage-catalog-ads).
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
 
-```ts
-metaPixelEvent('ViewContent', {
-  content_ids: ['SKU-123'],
-  content_type: 'product',
-  value: 49.99,
-  currency: 'USD',
-});
-```
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
 
-For collaborative ads, Meta requires `content_type: 'product'`; `AddToCart` and `Purchase` also require `contents`, `currency`, and `value`. See Meta's [collaborative ads pixel guide](https://developers.facebook.com/docs/meta-pixel/implementation/pixel-for-collaborative-ads).
+  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
-metaPixelEvent('AddToCart', {
-  contents: [{ id: 'SKU-123', quantity: 2 }],
-  content_type: 'product',
-  value: 99.98,
-  currency: 'USD',
-});
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-## Movies
+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.
 
-Meta's [movies pixel guide](https://developers.facebook.com/docs/meta-pixel/implementation/pixel-for-movies) uses the standard events `ViewContent`, `InitiateCheckout`, `Purchase`, and `PageView` with movie-specific parameters such as `movieref`.
+**SvelteKit**
 
-```ts
-metaPixelEvent('InitiateCheckout', {
-  content_ids: ['movie-1|theater-1|2026-05-11T19:30:00-07:00'],
-  movieref: 'fb_movies',
-  num_items: 2,
-});
-```
+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).
 
-## Multiple pixels
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
 
-Meta's [multiple pixel guidance](https://developers.facebook.com/docs/facebook-pixel/implementation/accurate_event_tracking) warns that `fbq('track', ...)` and `fbq('trackCustom', ...)` fire for every initialized pixel ID. If another integration or tag manager initializes more than one pixel, use the single-pixel helpers to prevent overfiring.
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
 
-```ts
-import {
-  metaPixelSingleCustomEvent,
-  metaPixelSingleEvent,
-} from '@c15t/scripts/meta-pixel';
-
-metaPixelSingleEvent('PIXEL-A', 'Purchase', {
-  value: 149.97,
-  currency: 'USD',
-});
-
-metaPixelSingleCustomEvent('PIXEL-B', 'Step4', {
-  funnel: 'checkout',
-});
+<ConsentManagerProvider {mode} {scripts} prefetch={data.prefetch}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentManagerProvider>
 ```
 
-## Custom audiences and sharing
-
-Meta custom audiences are configured in Events Manager after standard events, custom events, or custom conversions are being received. The c15t integration sends the browser events; audience rules are managed in Meta. See Meta's [custom audiences guide](https://developers.facebook.com/docs/facebook-pixel/implementation/custom-audiences).
-
-Pixel sharing between businesses or agencies is also managed through Meta Business Manager or the Business Management APIs, not through the browser script. See Meta's [pixel sharing guide](https://developers.facebook.com/docs/marketing-api/business-asset-management/guides/business-pixel-sharing).
+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.
 
-## Types
-
-### MetaPixelOptions
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`MetaPixelOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts\`|
-
-\*ExtractedTypeTable: Could not extract "MetaPixelOptions" from "./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-### MetaPixelDataProcessingOptions
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`MetaPixelDataProcessingOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts\`|
-
-\*ExtractedTypeTable: Could not extract "MetaPixelDataProcessingOptions" from "./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
-
-### MetaPixelEventOptions
-
-|Property|Value|
-|:--|:--|
-|Type Name|\`MetaPixelEventOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts\`|
+**JavaScript**
 
-\*ExtractedTypeTable: Could not extract "MetaPixelEventOptions" from "./packages/scripts/src/vendors/ads-and-pixels/meta-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()`:
 
-### Script
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+const loader = createScriptLoader({ kernel, scripts });
+```
 
-\*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.\*
+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).
 
-### StandardEventParams
+## Keep event calls behind permission
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`StandardEventParams\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts\`|
+Initialization and later application events are separate responsibilities. If
+application code calls `fbq` directly, check effective marketing permission
+before each optional event and ensure the API is available. Do not assume a
+function still present on `window` means the visitor still permits tracking.
 
-\*ExtractedTypeTable: Could not extract "StandardEventParams" from "./packages/scripts/src/vendors/ads-and-pixels/meta-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+For an opt-in policy, verify no pixel script or collection request occurs before
+permission or after rejection. Grant permission, send a test event, revoke and
+confirm future application events stop. Check navigation for duplicate page
+views. See [verification](../guides/verify-consent.md).