X Pixel
X Pixel records website conversions and builds audiences for X Ads campaigns.
Use useScriptXPixel() to load the pixel and access its twq API.
Nuxt Config Setup
Add this to your nuxt.config.ts to load X Pixel globally. Alternatively you can use the useScriptXPixel composable for more control.
export default defineNuxtConfig({
scripts: {
registry: {
xPixel: {
id: 'oxxxxxx',
trigger: 'onNuxtReady',
}
}
}
})This config automatically enables first-party mode (bundle + proxy). See below to customise.
useScriptXPixel()
The useScriptXPixel composable lets you have fine-grain control over when and how X Pixel is loaded on your site.
const { proxy } = useScriptXPixel()
proxy.twq('event', 'tw-xxxxx-xxxxx')Please follow the Registry Scripts guide to learn more about advanced usage.
First-Party Mode: Privacy Focused Proxy
No extra config needed. The script is bundled from your domain (faster loads, no extra DNS lookup) and runtime requests are reverse-proxied through your server with automatic anonymisation (user IPs stay hidden from X Pixel, works with ad blockers). Learn more.
export default defineNuxtConfig({
scripts: {
// ✅ First-party mode: bundled + proxied
registry: {
xPixel: {
id: 'oxxxxxx',
trigger: 'onNuxtReady',
},
},
},
})Example
Using X Pixel in a component with the proxy to send events .
<script setup lang="ts">
const { proxy } = useScriptXPixel()
// noop in development, ssr
// just works in production, client
function handleAction() {
proxy.twq('event', 'tw-xxxxx-xxxxx')
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template>Browser and server event deduplication
When you send the same conversion from the browser and a server integration, give both events the same unique conversion_id. X uses that value to deduplicate the pair, as described in its conversion-tracking guide:
const { proxy } = useScriptXPixel({ id: 'YOUR_PIXEL_ID' })
proxy.twq('event', 'YOUR_EVENT_ID', {
conversion_id: order.id,
value: order.total,
currency: 'USD',
contents: order.items.map(item => ({
content_id: item.id,
num_items: item.quantity,
})),
})
The current Nuxt Scripts type requires contents for every event. X lists it as an event parameter rather than a universal requirement; only its Dynamic Product Ads instructions require it for all events. Include it for now or narrow through a local wrapper if your event has no item data.
idstring required Your X (Twitter) Pixel ID.
versionstring = '1.1'The X Pixel script version.