@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/hightouch.md

@@ -1,199 +1,293 @@
 ---
 title: Hightouch
-description: Load Hightouch Events with c15t and gate the browser SDK behind
-  measurement consent.
+description: Configure Hightouch with c15t v3, understand measurement permission
+  and verify loading and revocation.
 group: integrations
-icon: hightouch
 ---
-[Hightouch Events](https://hightouch.com/docs/events/overview) collects customer behavior from websites and sends it into Hightouch for warehouse-backed analytics, activation, and real-time workflows. The `hightouch()` helper creates Hightouch's `window.htevents` queue, records the write key and optional API host for the standalone loader, optionally queues the initial `page()` call, and loads the browser SDK when `measurement` consent is available.
 
-## Integrate with c15t
+## Configure Hightouch
 
-**React**
+Copy the write key from the Hightouch Event Source. The helper initializes `htevents` and queues an initial page call by default.
 
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
-import { hightouch } from '@c15t/scripts/hightouch';
+| 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 = [
-  hightouch({
-    writeKey: 'WRITE_KEY',
-    apiHost: 'us-east-1.hightouch-events.com',
-  }),
-];
+```ts title="src/consent-scripts.ts"
+import { hightouch } from '@c15t/scripts/hightouch';
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const scripts = [hightouch({ writeKey: 'YOUR_EVENT_SOURCE_WRITE_KEY' })];
 ```
 
+## 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 { hightouch } from '@c15t/scripts/hightouch';
+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**
 
-const scripts = [
-  hightouch({
-    writeKey: 'WRITE_KEY',
-    apiHost: 'us-east-1.hightouch-events.com',
-  }),
-];
+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).
+
+```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 { hightouch } from '@c15t/scripts/hightouch';
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    hightouch({
-      writeKey: 'WRITE_KEY',
-      apiHost: 'us-east-1.hightouch-events.com',
-    }),
-  ],
-});
+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:** `measurement` (Analytics)
-* **Loads when:** measurement consent is granted
-* **On revocation:** unloaded - c15t removes the script element it created. The `window.htevents` runtime object is left in place until the next page load (c15t reloads the page on revocation by default), so treat the load gate as the consent boundary.
+**Nuxt**
 
-The helper maps Hightouch's browser snippet into the manifest engine:
+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
-hightouch({
-  writeKey: 'WRITE_KEY',
-  apiHost: 'us-east-1.hightouch-events.com',
+```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>
 ```
 
-It creates `window.htevents`, defines the official queue methods, queues:
+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
-window.htevents.load('WRITE_KEY', {
-  apiHost: 'us-east-1.hightouch-events.com',
+**Vue**
+
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
+
+```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 });
 });
-window.htevents.page();
+onUnmounted(() => loader?.dispose());
+</script>
+
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
 ```
 
-and loads:
+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).
+
+**Astro**
 
-```txt
-https://cdn.hightouch-events.com/browser/release/v1-latest/events.min.js
+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:
+
+```js title="astro.config.mjs"
+import { fileURLToPath } from 'node:url';
 ```
 
-`writeKey` is required and must be a non-empty string after trimming. `apiHost` is optional; Hightouch's SDK defaults to `us-east-1.hightouch-events.com`, so pass it only when your Event Source uses another region or a first-party tracking host.
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
 
-## Configure page tracking
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
+```
 
-By default the helper queues `htevents.page()` before the vendor bundle loads. If you want to handle page views yourself, set `trackPageView` to `false`.
+Export the scripts from that module:
 
-```ts
-import { hightouch } from '@c15t/scripts/hightouch';
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
 
-hightouch({
-  writeKey: 'WRITE_KEY',
-  trackPageView: false,
-});
+export default { scripts } satisfies C15tClientOptionsExtension;
 ```
 
-To proxy or self-host the loader, pass a custom URL:
+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
-hightouch({
-  writeKey: 'WRITE_KEY',
-  scriptUrl: 'https://analytics.example.com/events.min.js',
-});
-```
+**Svelte**
 
-## Consent behavior
+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 { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
 
-c15t blocks the Hightouch SDK from loading until `measurement` consent is granted and unloads it on revocation. Hightouch does not expose a browser API that prevents collection while loaded — the SDK writes identifiers and delivers events to Hightouch as soon as it runs — so gating the load is the only default that reliably honors missing or denied consent. See the [RudderStack consent notes](/docs/integrations/rudderstack#consent-behavior) for the full reasoning behind this model versus vendor consent-API mapping (as used for Google Tag Manager).
+  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>
 
-## Tracking events in your app
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
 
-c15t gates the Hightouch browser SDK from loading until `measurement` consent is granted. Your application code that calls Hightouch's runtime API (`window.htevents.track`, `identify`, etc.) is **not** automatically gated - `window.htevents` does not exist until c15t initializes the integration, so unguarded calls made before that (or while consent is denied) throw. Once the integration is initialized with consent, early calls queue normally until the SDK finishes loading.
+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.
 
-Guard event calls by checking consent state. From React:
+**SvelteKit**
 
-```tsx
-import { useCallback } from 'react';
-import { useConsentManager } from '@c15t/react';
+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).
 
-function SignupExample() {
-  const { has } = useConsentManager();
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
 
-  const trackSignup = useCallback(() => {
-    if (has('measurement')) {
-      window.htevents?.track('Signup Completed', { plan: 'pro' });
-    }
-  }, [has]);
-}
+  let { children, data } = $props();
+  const mode = hosted({ url: data.backendURL });
+</script>
+
+<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.htevents?.track('Signup Completed', { plan: 'pro' });
-}
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
 ```
 
-## Types
+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).
+
+## Options
 
-### HightouchOptions
+| Option          | Behavior                                                           |
+| --------------- | ------------------------------------------------------------------ |
+| `writeKey`      | Required non-empty Event Source write key.                         |
+| `apiHost`       | Optional API host for another region or first-party tracking host. |
+| `trackPageView` | Defaults to `true`; set `false` when your router owns page calls.  |
+| `scriptUrl`     | Optional full loader override.                                     |
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`HightouchOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/analytics/hightouch.ts\`|
+## Consent behavior
 
-\*ExtractedTypeTable: Could not extract "HightouchOptions" from "./packages/scripts/src/vendors/analytics/hightouch.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Measurement permission gates the SDK. Hightouch destinations can forward events beyond the browser SDK; configure destination purposes and stop application event calls after revocation. The helper has no vendor shutdown callback.
 
-### Script
+## Verify the integration
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Confirm the intended API host receives events and that the initial page event is not duplicated by your router. Check downstream destinations as well as browser requests.
 
-\*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
+`measurement`, 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).