@c15t/scripts 2.2.0 → 3.0.0-alpha.0

package/docs/integrations/linkedin-insights.md

@@ -1,161 +1,291 @@
 ---
-title: LinkedIn Insights
-description: Track conversions and build matched audiences for LinkedIn
-  advertising campaigns.
-icon: linkedin
+title: LinkedIn Insight Tag
+description: Configure LinkedIn Insight Tag with c15t v3, understand marketing
+  permission and verify loading and revocation.
 group: integrations
 ---
-LinkedIn Insight Tag is LinkedIn's conversion tracking and audience matching tool for LinkedIn advertising campaigns. It tracks website actions, measures ad performance, builds website retargeting audiences, and provides aggregate audience insights about visitors from LinkedIn member accounts.
 
-## Official LinkedIn documentation
+## Configure LinkedIn Insight Tag
 
-* [Add the LinkedIn Insight Tag to your website](https://www.linkedin.com/help/lms/answer/a418880)
-* [LinkedIn Insight Tag overview](https://www.linkedin.com/help/lms/answer/a489169)
-* [LinkedIn Insight Tag FAQs](https://www.linkedin.com/help/lms/answer/a427660)
-* [Insight Tag source status](https://www.linkedin.com/help/lms/answer/a488323)
-* [Compatible tag management systems](https://www.linkedin.com/help/lms/answer/a422760)
-* [LinkedIn Ads Agreement](https://www.linkedin.com/legal/sas-terms)
+Use the Insight Tag partner ID from LinkedIn Campaign Manager. The helper sets the partner globals and loads the Insight Tag.
 
-## Integrate with c15t
+| Package manager | Command                     |
+| :-------------- | :-------------------------- |
+| npm             | `npm install @c15t/scripts` |
+| pnpm            | `pnpm add @c15t/scripts`    |
+| yarn            | `yarn add @c15t/scripts`    |
+| bun             | `bun add @c15t/scripts`     |
 
-**React**
-
-```tsx
-import { type ReactNode } from 'react';
-import { ConsentManagerProvider } from '@c15t/react';
+```ts title="src/consent-scripts.ts"
 import { linkedinInsights } from '@c15t/scripts/linkedin-insights';
 
-const scripts = [
-  linkedinInsights({
-    id: '123456789012345',
-  }),
-];
-
-export function ConsentProvider({ children }: { children: ReactNode }) {
-  return (
-    <ConsentManagerProvider
-      options={{
-        mode: 'hosted',
-        backendURL: 'https://your-instance.c15t.dev',
-        scripts,
-      }}
-    >
-      {children}
-    </ConsentManagerProvider>
-  );
-}
+export const scripts = [linkedinInsights({ id: 'YOUR_PARTNER_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 { linkedinInsights } from '@c15t/scripts/linkedin-insights';
+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 = [
-  linkedinInsights({
-    id: '123456789012345',
-  }),
-];
+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).
 
-export function ConsentProvider({ children }: { children: ReactNode }) {
+```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 (
-    <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 { linkedinInsights } from '@c15t/scripts/linkedin-insights';
+import { ConsentProvider } from 'c15t/react';
+import { scripts } from './consent-scripts';
+```
+
+Keep the existing options and add `scripts`:
+
+```tsx
+<ConsentProvider options={{ ...consentOptions, scripts }}>
+  {children}
+</ConsentProvider>
+```
+
+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).
+
+**Nuxt**
+
+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.
+
+```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;
 
-getOrCreateConsentRuntime({
-  mode: 'hosted',
-  backendURL: 'https://your-instance.c15t.dev',
-  scripts: [
-    linkedinInsights({
-      id: '123456789012345',
-    }),
-  ],
+const removeMountedHook = nuxtApp.hook('app:mounted', () => {
+  loader = createScriptLoader({ kernel, scripts });
 });
+onUnmounted(() => {
+  removeMountedHook();
+  loader?.dispose();
+});
+</script>
+
+<template>
+  <ConsentRoot />
+  <NuxtPage />
+</template>
 ```
 
-## How c15t loads it
+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).
 
-* **Category:** `marketing` (Ads & Pixels)
-* **Loads when:** marketing consent is granted
-* **Default install:** c15t sets the LinkedIn partner ID globals, seeds the `lintrk` queue, and loads LinkedIn's `insight.min.js`
-* **On revocation:** unloaded - c15t removes the script element from the DOM
+**Vue**
 
-> ⚠️ **Warning:**
-> LinkedIn says the Insight Tag should not be installed on pages that collect or contain Sensitive Data, including certain consumer health or financial pages. If your app has those pages, only include this script on eligible routes and confirm the placement with your legal team.
+Use the kernel already provided by the Vue plugin. Merge this setup into
+`App.vue`, whose lifetime covers the application:
 
-Use the LinkedIn Insight Tag partner ID as `id`. You can find it in Campaign Manager under **Data** -> **Signals manager** -> **Insight Tag**.
+```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';
 
-c15t intentionally does not add LinkedIn's `<noscript>` image pixel fallback. The integration is consent-gated JavaScript, so the script only loads after `marketing` consent is granted.
+const kernel = useConsentKernel();
+let loader: ReturnType<typeof createScriptLoader> | undefined;
 
-## Tracking events in your app
+onMounted(() => {
+  loader = createScriptLoader({ kernel, scripts });
+});
+onUnmounted(() => loader?.dispose());
+</script>
 
-c15t gates the LinkedIn Insight Tag from loading until `marketing` consent is granted. Page tracking is automatic once the script loads, but if you fire custom conversions through `window.lintrk(...)`, those calls are **not** automatically gated - `window.lintrk` does not exist before consent is granted, and is removed again if consent is revoked.
+<template>
+  <ConsentRoot />
+  <main>Your application</main>
+</template>
+```
 
-Guard custom conversion calls by checking consent state:
+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).
 
-```tsx
-import { useCallback } from 'react';
-import { useConsentManager } from '@c15t/react';
-
-function useTrackSignup() {
-  const { has } = useConsentManager();
-  return useCallback(() => {
-    if (has('marketing')) {
-      window.lintrk?.('track', { conversion_id: 12345 });
-    }
-  }, [has]);
-}
+**Astro**
 
-function SignupButton() {
-  const trackSignup = useTrackSignup();
-  return <button onClick={trackSignup}>Sign up</button>;
-}
+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';
+```
+
+Add this option to the existing `c15t({ ... })` call. Resolve the path from
+the configuration file because Astro injects the import into a virtual module:
+
+```js
+clientEntrypoint: fileURLToPath(new URL('./src/c15t.client.ts', import.meta.url)),
 ```
 
-## Verify setup
+Export the scripts from that module:
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from '@c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+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.
+
+**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 { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from './consent-scripts';
 
-LinkedIn validates the tag after an associated domain or URL receives traffic. Source status can take a few minutes and up to 24 hours to update after the first page load:
+  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>
+
+<ConsentManagerProvider {mode} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentManagerProvider>
+```
+
+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).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentManagerProvider, hosted } from '@c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  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>
+```
+
+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**
+
+Attach the loader to your existing kernel before calling
+`kernel.commands.init()`:
+
+```ts
+import { createScriptLoader } from 'c15t/modules/script-loader';
+import { scripts } from './consent-scripts';
+
+const loader = createScriptLoader({ kernel, scripts });
+```
 
-* **Active:** signal received in the past seven days
-* **No recent activity:** no signal for more than seven days
-* **Unverified:** no signal received yet
+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).
 
-## Types
+## Options
 
-### LinkedInInsightsOptions
+| Option      | Behavior                                                           |
+| ----------- | ------------------------------------------------------------------ |
+| `id`        | Required Insight Tag partner ID.                                   |
+| `scriptSrc` | Optional loader override. Defaults to LinkedIn's `insight.min.js`. |
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`LinkedInInsightsOptions\`|
-|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/linkedin-insights.ts\`|
+## Consent behavior
 
-\*ExtractedTypeTable: Could not extract "LinkedInInsightsOptions" from "./packages/scripts/src/vendors/ads-and-pixels/linkedin-insights.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*
+Marketing permission gates the loader. There is no helper-provided LinkedIn revocation callback. Keep conversion calls behind current marketing permission.
 
-### Script
+## Verify the integration
 
-|Property|Value|
-|:--|:--|
-|Type Name|\`Script\`|
-|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|
+Remove the original snippet and any tracking image. Confirm the partner ID and inspect conversion requests after grant, navigation and revocation.
 
-\*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).