X Pixel
在你的 Nuxt 应用中使用 X Pixel。
X Pixel 让你能够收集、清理并控制你的客户数据。X 帮助你了解客户并个性化他们的体验。
Nuxt Scripts 提供了一个注册脚本组合式函数 useScriptXPixel，以便在你的 Nuxt 应用中轻松集成 X Pixel。
Nuxt 配置设置
在你的 Nuxt 应用中全局加载 Meta Pixel 的最简单方式是使用 Nuxt 配置。或者，你也可以直接使用 useScriptXPixel 组合式函数。
如果你不打算发送自定义事件，可以使用 环境覆盖 在开发环境中禁用该脚本。
export default defineNuxtConfig({
scripts: {
registry: {
xPixel: {
id: 'YOUR_ID'
}
}
}
})
export default defineNuxtConfig({
$production: {
scripts: {
registry: {
xPixel: {
id: 'YOUR_ID',
}
}
}
}
})
使用环境变量
如果你更倾向于使用环境变量来配置你的 id。
nuxt.config.ts
export default defineNuxtConfig({
scripts: {
registry: {
xPixel: true,
}
},
// 你需要提供运行时配置以访问环境变量
runtimeConfig: {
public: {
scripts: {
xPixel: {
id: '', // NUXT_PUBLIC_SCRIPTS_X_PIXEL_ID
},
},
},
},
})
.env
NUXT_PUBLIC_SCRIPTS_X_PIXEL_ID=<YOUR_ID>
useScriptXPixel
useScriptXPixel 组合式函数让你可以精细控制 X Pixel 在你的网站上的加载时机和方式。
const { proxy } = useScriptXPixel({
id: 'YOUR_ID'
})
// 示例
proxy.twq('event', '<EventId>', {
value: 1,
})
请参阅注册脚本指南以了解更多高级用法。
XPixelApi
export interface XPixelApi {
twq: TwqFns & {
loaded: boolean
version: string
queue: any[]
}
}
type TwqFns =
((event: 'event', eventId: string, data?: EventObjectProperties) => void)
& ((event: 'config', id: string) => void)
& ((event: string, ...params: any[]) => void)
interface ContentProperties {
content_type?: string | null
content_id?: string | number | null
content_name?: string | null
content_price?: string | number | null
num_items?: string | number | null
content_group_id?: string | number | null
}
interface EventObjectProperties {
value?: string | number | null
currency?: string | null
conversion_id?: string | number | null
email_address?: string | null
phone_number?: string | null
contents: ContentProperties[]
}
配置模式
首次设置该脚本时必须提供选项。
export const XPixelOptions = object({
id: string(),
version: optional(string()),
})
First-Party 模式
该脚本支持第一方模式，可通过你的域名路由所有流量，以提升隐私保护并绕过广告拦截器。
当通过 scripts.firstParty: true 全局启用时，该脚本将会：
- 从你的域名加载，而非
analytics.twitter.com - 通过你的服务器路由跟踪请求（
t.co） - 完全的隐私匿名化 — IP、用户代理、语言、屏幕、时区和硬件指纹均被匿名处理（针对不可信的广告网络）
nuxt.config.ts
export default defineNuxtConfig({
scripts: {
firstParty: true,
registry: {
xPixel: { id: 'YOUR_ID' }
}
}
})
若你想为此特定脚本选择退出此模式：
useScriptXPixel({
id: 'YOUR_ID',
scriptOptions: {
firstParty: false // 直接从 X/Twitter 加载
}
})
示例
仅在生产环境中使用 X Pixel，同时使用 twq 发送转化事件。
<script setup lang="ts">
const { proxy } = useScriptXPixel()
// 在开发环境和 SSR 中无操作
// 仅在生产环境客户端生效
function sendConversion() {
proxy.twq('event', 'Purchase', {
value: 1,
currency: 'USD'
})
}
</script>
<template>
<div>
<button @click="sendConversion">
发送转化
</button>
</div>
</template>