c15t/docs/integrations/amplitude.md

Headless JavaScript consent management platform for cookie banners, privacy preferences, consent storage, and script gating.

---
title: Amplitude
description: Load Amplitude Browser SDK 2 with c15t and gate product analytics
  behind measurement consent.
group: integrations
icon: amplitude
---
[Amplitude](https://amplitude.com/) provides product analytics for tracking user behavior, funnels, retention, and feature adoption. The `amplitude()` helper creates the Browser SDK 2 snippet queue, queues `amplitude.init(apiKey, initOptions)`, and loads Amplitude only when `measurement` consent is available.

## Integrate with c15t

**React**

```tsx
import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/react';
import { amplitude } from '@c15t/scripts/amplitude';

const scripts = [
  amplitude({
    apiKey: 'AMPLITUDE_API_KEY',
    initOptions: {
      autocapture: false,
    },
  }),
];

export function ConsentProvider({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'hosted',
        backendURL: 'https://your-instance.c15t.dev',
        scripts,
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}
```

**Next.js**

```tsx
'use client';

import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/nextjs';
import { amplitude } from '@c15t/scripts/amplitude';

const scripts = [
  amplitude({
    apiKey: 'AMPLITUDE_API_KEY',
    initOptions: {
      autocapture: false,
    },
  }),
];

export function ConsentProvider({ children }: { children: ReactNode }) {
  return (
    <ConsentManagerProvider
      options={{
        mode: 'hosted',
        backendURL: '/api/c15t',
        scripts,
      }}
    >
      {children}
    </ConsentManagerProvider>
  );
}
```

**JavaScript**

```ts
import { getOrCreateConsentRuntime } from 'c15t';
import { amplitude } from '@c15t/scripts/amplitude';

getOrCreateConsentRuntime({
  mode: 'hosted',
  backendURL: 'https://your-instance.c15t.dev',
  scripts: [
    amplitude({
      apiKey: 'AMPLITUDE_API_KEY',
      initOptions: {
        autocapture: false,
      },
    }),
  ],
});
```

## How c15t loads it

* **Category:** `measurement` (Analytics)
* **Loads when:** measurement consent is granted
* **On revocation:** c15t calls `amplitude.setOptOut(true)` through the lifecycle callback and unloads the script by default.

The helper maps Amplitude Browser SDK 2's script-loader contract into the manifest engine:

```ts
amplitude({
  apiKey: 'AMPLITUDE_API_KEY',
  initOptions: {
    autocapture: false,
  },
});
```

It creates `window.amplitude` with:

* `invoked: true`
* `_q: []` for queued `{ name, args, resolve }` method calls
* `_iq: {}` for the named-instance registry expected by the SDK
* `Identify` for queued pre-load identify operations
* core queue methods for `init`, `track`, `identify`, `setUserId`, `setOptOut`, and `flush`

Then it queues:

```ts
window.amplitude.init('AMPLITUDE_API_KEY', {
  autocapture: false,
});
```

and loads:

```txt
https://cdn.amplitude.com/libs/analytics-browser-2.44.4-min.js.gz
```

`apiKey` is required and must be a non-empty string after trimming.

## Configure initialization

Pass `initOptions` to provide Amplitude Browser SDK 2 initialization options. Values must be JSON-serializable: plain objects, arrays, strings, numbers, booleans, and `null`.

```ts
import { amplitude } from '@c15t/scripts/amplitude';

amplitude({
  apiKey: 'AMPLITUDE_API_KEY',
  initOptions: {
    autocapture: false,
    fetchRemoteConfig: false,
  },
});
```

Do not pass functions, Dates, Maps, Sets, class instances, symbols, or other non-JSON values in `initOptions`.

## Configure the loader URL

Amplitude's Browser SDK 2 CDN bundle path is versioned. c15t pins a tested default version and lets you override the URL if you self-host or proxy the bundle.

```ts
amplitude({
  apiKey: 'AMPLITUDE_API_KEY',
  scriptUrl: 'https://analytics.example.com/analytics-browser.js',
});
```

## Consent behavior

Amplitude should not load before analytics consent. c15t gates the SDK on `measurement` consent and queues `init()` only when the script is allowed to load.

After the SDK has loaded, the generated lifecycle callback maps consent changes to Amplitude's runtime opt-out API:

```ts
window.amplitude.setOptOut(false); // measurement granted
window.amplitude.setOptOut(true); // measurement denied
```

The script still uses c15t's default unload behavior when measurement consent is revoked.

## Tracking events in your app

c15t gates the Amplitude browser SDK from loading until `measurement` consent is granted. Your application code that calls Amplitude's runtime API (`window.amplitude.track`, `identify`, etc.) is **not** automatically gated - `window.amplitude` does not exist until the script is loaded, so unguarded calls before consent throw.

Guard event calls by checking consent state. From React:

```tsx
import { useCallback } from 'react';
import { useConsentManager } from '@c15t/react';

function SignupExample() {
  const { has } = useConsentManager();

  const trackSignup = useCallback(() => {
    if (has('measurement')) {
      window.amplitude?.track('Signup Completed', { plan: 'pro' });
    }
  }, [has]);
}
```

From plain JavaScript:

```ts
import { getOrCreateConsentRuntime } from 'c15t';

const { consentStore } = getOrCreateConsentRuntime();

if (consentStore.getState().has('measurement')) {
  window.amplitude?.track('Signup Completed', { plan: 'pro' });
}
```

## Types

### AmplitudeOptions

|Property|Value|
|:--|:--|
|Type Name|\`AmplitudeOptions\`|
|Source Path|\`./packages/scripts/src/vendors/analytics/amplitude.ts\`|

\*ExtractedTypeTable: Could not extract "AmplitudeOptions" from "./packages/scripts/src/vendors/analytics/amplitude.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

### Script

|Property|Value|
|:--|:--|
|Type Name|\`Script\`|
|Source Path|\`./packages/core/src/libs/script-loader/types.ts\`|

\*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.\*