c15t/docs/integrations/x-pixel.md

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

---
title: X Pixel (Twitter Pixel)
description: Track conversions and build audiences for advertising campaigns on
  X (formerly Twitter).
icon: x
group: integrations
---
X Pixel (formerly Twitter Pixel) is X's conversion tracking and audience building tool. It helps you measure ad performance, retarget website visitors, and optimize campaigns on the X platform.

## Official X documentation

* [Conversion tracking for websites (X Ads Help)](https://business.x.com/en/help/campaign-measurement-and-analytics/conversion-tracking-for-websites)

## Integrate with c15t

**React**

```tsx
import { type ReactNode } from 'react';
import { ConsentManagerProvider } from '@c15t/react';
import { xPixel } from '@c15t/scripts/x-pixel';

const scripts = [xPixel({ pixelId: '123456789012345' })];

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 { xPixel } from '@c15t/scripts/x-pixel';

const scripts = [xPixel({ pixelId: '123456789012345' })];

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

**JavaScript**

```ts
import { getOrCreateConsentRuntime } from 'c15t';
import { xPixel } from '@c15t/scripts/x-pixel';

getOrCreateConsentRuntime({
  mode: 'hosted',
  backendURL: 'https://your-instance.c15t.dev',
  scripts: [xPixel({ pixelId: '123456789012345' })],
});
```

## How c15t loads it

* **Category:** `marketing` (Ads & Pixels)
* **Loads when:** marketing consent is granted
* **On revocation:** unloaded — c15t removes the script element from the DOM

## Configure the integration

You can use the `xPixelEvent` function to track events. This is a wrapper around the `twq` function that the X Pixel script uses.

```ts
import { xPixelEvent } from '@c15t/scripts/x-pixel';

xPixelEvent('tw-xxxx-xxxx', { value: 10.00, currency: 'USD' });
```

## Tracking events in your app

c15t gates the X Pixel script from loading until `marketing` consent is granted. Your application code that calls `twq` or the `xPixelEvent` helper is **not** automatically gated — `window.twq` does not exist before consent is granted, and is removed again if consent is revoked. Unguarded calls throw.

Guard event calls by checking consent state:

```tsx
import { useCallback } from 'react';
import { useConsentManager } from '@c15t/react';
import { xPixelEvent } from '@c15t/scripts/x-pixel';

function useTrackPurchase() {
  const { has } = useConsentManager();
  return useCallback(() => {
    if (has('marketing')) {
      xPixelEvent('tw-xxxx-xxxx', { value: 10.0, currency: 'USD' });
    }
  }, [has]);
}

function PurchaseButton() {
  const trackPurchase = useTrackPurchase();
  return <button onClick={trackPurchase}>Complete purchase</button>;
}
```

## Types

### XPixelOptions

|Property|Value|
|:--|:--|
|Type Name|\`XPixelOptions\`|
|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts\`|

\*ExtractedTypeTable: Could not extract "XPixelOptions" from "./packages/scripts/src/vendors/ads-and-pixels/x-pixel.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.\*

### XPixelEvent

|Property|Value|
|:--|:--|
|Type Name|\`XPixelEvent\`|
|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts\`|

\*ExtractedTypeTable: Could not extract "XPixelEvent" from "./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*

### XPixelContent

|Property|Value|
|:--|:--|
|Type Name|\`XPixelContent\`|
|Source Path|\`./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts\`|

\*ExtractedTypeTable: Could not extract "XPixelContent" from "./packages/scripts/src/vendors/ads-and-pixels/x-pixel.ts" using base path "/home/runner/work/c15t/c15t". Verify the path/name and that the file is included by your tsconfig.\*