TikTok Pixel

在你的 Nuxt 应用中使用 TikTok Pixel。

TikTok Pixel 让你能够衡量、优化并构建 TikTok 广告活动的受众。

Nuxt Scripts 提供了注册脚本组合函数 useScriptTikTokPixel，轻松地在你的 Nuxt 应用中集成 TikTok Pixel。

Nuxt 配置设置

在 Nuxt 应用中全局加载 TikTok Pixel 最简单的方式是使用 Nuxt 配置。你也可以直接使用 useScriptTikTokPixel 组合函数。

如果你不打算发送自定义事件，可以使用环境配置覆盖在开发环境中禁用该脚本。

export default defineNuxtConfig({
  scripts: {
    registry: {
      tiktokPixel: {
        id: 'YOUR_PIXEL_ID'
      }
    }
  }
})

export default defineNuxtConfig({
  $production: {
    scripts: {
      registry: {
        tiktokPixel: {
          id: 'YOUR_PIXEL_ID'
        }
      }
    }
  }
})

使用环境变量

如果你更倾向于使用环境变量配置你的 id。

nuxt.config.ts

export default defineNuxtConfig({
  scripts: {
    registry: {
      tiktokPixel: true,
    }
  },
  // 需要提供运行时配置以访问环境变量
  runtimeConfig: {
    public: {
      scripts: {
        tiktokPixel: {
          id: '', // 对应 NUXT_PUBLIC_SCRIPTS_TIKTOK_PIXEL_ID
        },
      },
    },
  },
})

.env

NUXT_PUBLIC_SCRIPTS_TIKTOK_PIXEL_ID=<YOUR_ID>

useScriptTikTokPixel

useScriptTikTokPixel 组合函数让你能够细粒度地控制 TikTok Pixel 在你网站上的加载时机和方式。

const { proxy } = useScriptTikTokPixel({
  id: 'YOUR_PIXEL_ID'
})

// 跟踪事件
proxy.ttq('track', 'ViewContent', {
  content_id: '123',
  content_name: '产品名称',
  value: 99.99,
  currency: 'USD'
})

请参考注册脚本指南了解更多高级用法。

TikTokPixelApi

export interface TikTokPixelApi {
  ttq: TtqFns & {
    push: TtqFns
    loaded: boolean
    queue: any[]
  }
}

type TtqFns =
  & ((cmd: 'track', event: StandardEvents | string, properties?: EventProperties) => void)
  & ((cmd: 'page') => void)
  & ((cmd: 'identify', properties: IdentifyProperties) => void)
  & ((cmd: string, ...args: any[]) => void)

type StandardEvents =
  | 'ViewContent' | 'ClickButton' | 'Search' | 'AddToWishlist'
  | 'AddToCart' | 'InitiateCheckout' | 'AddPaymentInfo' | 'CompletePayment'
  | 'PlaceAnOrder' | 'Contact' | 'Download' | 'SubmitForm'
  | 'CompleteRegistration' | 'Subscribe'

配置 Schema

首次设置脚本时必须提供选项。

export const TikTokPixelOptions = object({
  id: string(),
  trackPageView: optional(boolean()), // 默认: true
})

First-Party 模式

此脚本支持 First-Party Mode，该模式通过你的域名路由所有流量，以提升隐私保护并绕过广告拦截器。

当在全局通过 scripts.firstParty: true 启用时，该脚本将：

从你的域名加载，而非 analytics.tiktok.com
通过你的服务器路由跟踪请求
完全隐私匿名化 — IP 地址、用户代理、语言、屏幕、时区和硬件指纹均被匿名化（不被信任的广告网络）

nuxt.config.ts

export default defineNuxtConfig({
  scripts: {
    firstParty: true,
    registry: {
      tiktokPixel: { id: 'YOUR_PIXEL_ID' }
    }
  }
})

如果你想为此脚本单独禁用该功能：

useScriptTikTokPixel({
  id: 'YOUR_PIXEL_ID',
  scriptOptions: {
    firstParty: false // 直接从 TikTok 加载
  }
})

示例

使用 TikTok Pixel 跟踪购买事件。

<script setup lang="ts">
const { proxy } = useScriptTikTokPixel()

function trackPurchase() {
  proxy.ttq('track', 'CompletePayment', {
    content_id: 'product-123',
    content_name: '超棒的产品',
    value: 49.99,
    currency: 'USD'
  })
}
</script>

<template>
  <button @click="trackPurchase">
    完成购买
  </button>
</template>

用户识别

你可以识别用户进行高级匹配：

const { proxy } = useScriptTikTokPixel()

proxy.ttq('identify', {
  email: 'user@example.com',
  phone_number: '+1234567890'
})

禁用自动页面浏览跟踪

默认情况下，TikTok Pixel 会自动追踪页面浏览。若要禁用：

export default defineNuxtConfig({
  scripts: {
    registry: {
      tiktokPixel: {
        id: 'YOUR_PIXEL_ID',
        trackPageView: false
      }
    }
  }
})

Snapchat 像素

在你的 Nuxt 应用中使用 Snapchat 像素。

X Pixel

在你的 Nuxt 应用中使用 X Pixel。