feat(registry): add TikTok Pixel script

docs/content/scripts/tracking/tiktok-pixel.md

@@ -0,0 +1,193 @@
+---
+title: TikTok Pixel
+description: Use TikTok Pixel in your Nuxt app.
+links:
+- label: Source
+  icon: i-simple-icons-github
+  to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/tiktok-pixel.ts
+  size: xs
+---
+
+[TikTok Pixel](https://ads.tiktok.com/help/article/tiktok-pixel) lets you measure, optimize and build audiences for your TikTok ad campaigns.
+
+Nuxt Scripts provides a registry script composable `useScriptTikTokPixel` to easily integrate TikTok Pixel in your Nuxt app.
+
+### Nuxt Config Setup
+
+The simplest way to load TikTok Pixel globally in your Nuxt App is to use Nuxt config. Alternatively you can directly
+use the [useScriptTikTokPixel](#usescripttiktokpixel) composable.
+
+If you don't plan to send custom events you can use the [Environment overrides](https://nuxt.com/docs/getting-started/configuration#environment-overrides) to
+disable the script in development.
+
+::code-group
+
+```ts [Always enabled]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      tiktokPixel: {
+        id: 'YOUR_PIXEL_ID'
+      }
+    }
+  }
+})
+```
+
+```ts [Production only]
+export default defineNuxtConfig({
+  $production: {
+    scripts: {
+      registry: {
+        tiktokPixel: {
+          id: 'YOUR_PIXEL_ID'
+        }
+      }
+    }
+  }
+})
+```
+
+::
+
+#### With Environment Variables
+
+If you prefer to configure your id using environment variables.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      tiktokPixel: true,
+    }
+  },
+  // you need to provide a runtime config to access the environment variables
+  runtimeConfig: {
+    public: {
+      scripts: {
+        tiktokPixel: {
+          id: '', // NUXT_PUBLIC_SCRIPTS_TIKTOK_PIXEL_ID
+        },
+      },
+    },
+  },
+})
+```
+
+```text [.env]
+NUXT_PUBLIC_SCRIPTS_TIKTOK_PIXEL_ID=<YOUR_ID>
+```
+
+## useScriptTikTokPixel
+
+The `useScriptTikTokPixel` composable lets you have fine-grain control over when and how TikTok Pixel is loaded on your site.
+
+```ts
+const { proxy } = useScriptTikTokPixel({
+  id: 'YOUR_PIXEL_ID'
+})
+
+// Track an event
+proxy.ttq('track', 'ViewContent', {
+  content_id: '123',
+  content_name: 'Product Name',
+  value: 99.99,
+  currency: 'USD'
+})
+```
+
+Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage.
+
+### TikTokPixelApi
+
+```ts
+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'
+```
+
+### Config Schema
+
+You must provide the options when setting up the script for the first time.
+
+```ts
+export const TikTokPixelOptions = object({
+  id: string(),
+  trackPageView: optional(boolean()), // default: true
+})
+```
+
+## Example
+
+Using TikTok Pixel to track a purchase event.
+
+::code-group
+
+```vue [PurchaseButton.vue]
+<script setup lang="ts">
+const { proxy } = useScriptTikTokPixel()
+
+function trackPurchase() {
+  proxy.ttq('track', 'CompletePayment', {
+    content_id: 'product-123',
+    content_name: 'Awesome Product',
+    value: 49.99,
+    currency: 'USD'
+  })
+}
+</script>
+
+<template>
+  <button @click="trackPurchase">
+    Complete Purchase
+  </button>
+</template>
+```
+
+::
+
+## Identifying Users
+
+You can identify users for advanced matching:
+
+```ts
+const { proxy } = useScriptTikTokPixel()
+
+proxy.ttq('identify', {
+  email: 'user@example.com',
+  phone_number: '+1234567890'
+})
+```
+
+## Disabling Auto Page View
+
+By default, TikTok Pixel tracks page views automatically. To disable:
+
+```ts
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      tiktokPixel: {
+        id: 'YOUR_PIXEL_ID',
+        trackPageView: false
+      }
+    }
+  }
+})
+```

src/registry.ts

@@ -111,6 +111,16 @@ export async function registry(resolve?: (path: string, opts?: ResolvePathOption
         from: await resolve('./runtime/registry/x-pixel'),
       },
     },
+    {
+      label: 'TikTok Pixel',
+      src: 'https://analytics.tiktok.com/i18n/pixel/events.js',
+      category: 'tracking',
+      logo: `<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 256 256"><path d="M224 72a52.059 52.059 0 0 1-52-52a4 4 0 0 0-4-4h-40a4 4 0 0 0-4 4v132a28 28 0 1 1-40.567-25.019a4 4 0 0 0 2.567-3.734V80a4 4 0 0 0-4.652-3.949A84.032 84.032 0 1 0 156 152v-43.047a99.432 99.432 0 0 0 52 14.586a4 4 0 0 0 4-4V76a4 4 0 0 0-4-4z" fill="currentColor"/></svg>`,
+      import: {
+        name: 'useScriptTikTokPixel',
+        from: await resolve('./runtime/registry/tiktok-pixel'),
+      },
+    },
     {
       label: 'Snapchat Pixel',
       src: 'https://sc-static.net/scevent.min.js',

src/runtime/registry/tiktok-pixel.ts

@@ -0,0 +1,98 @@
+import { useRegistryScript } from '../utils'
+import { object, string, optional, boolean } from '#nuxt-scripts-validator'
+import type { RegistryScriptInput } from '#nuxt-scripts/types'
+
+type StandardEvents
+  = 'ViewContent'
+    | 'ClickButton'
+    | 'Search'
+    | 'AddToWishlist'
+    | 'AddToCart'
+    | 'InitiateCheckout'
+    | 'AddPaymentInfo'
+    | 'CompletePayment'
+    | 'PlaceAnOrder'
+    | 'Contact'
+    | 'Download'
+    | 'SubmitForm'
+    | 'CompleteRegistration'
+    | 'Subscribe'
+
+interface EventProperties {
+  content_id?: string
+  content_type?: string
+  content_name?: string
+  contents?: Array<{ content_id: string, content_type?: string, content_name?: string, price?: number, quantity?: number }>
+  currency?: string
+  value?: number
+  description?: string
+  query?: string
+  [key: string]: any
+}
+
+interface IdentifyProperties {
+  email?: string
+  phone_number?: string
+  external_id?: string
+}
+
+type TtqFns
+  = ((cmd: 'track', event: StandardEvents | string, properties?: EventProperties) => void)
+    & ((cmd: 'page') => void)
+    & ((cmd: 'identify', properties: IdentifyProperties) => void)
+    & ((cmd: string, ...args: any[]) => void)
+
+export interface TikTokPixelApi {
+  ttq: TtqFns & {
+    push: TtqFns
+    loaded: boolean
+    queue: any[]
+  }
+}
+
+declare global {
+  interface Window extends TikTokPixelApi {}
+}
+
+export const TikTokPixelOptions = object({
+  id: string(),
+  trackPageView: optional(boolean()), // default true
+})
+
+export type TikTokPixelInput = RegistryScriptInput<typeof TikTokPixelOptions, true, false, false>
+
+export function useScriptTikTokPixel<T extends TikTokPixelApi>(_options?: TikTokPixelInput) {
+  return useRegistryScript<T, typeof TikTokPixelOptions>('tiktokPixel', options => ({
+    scriptInput: {
+      src: 'https://analytics.tiktok.com/i18n/pixel/events.js',
+      crossorigin: false,
+    },
+    schema: import.meta.dev ? TikTokPixelOptions : undefined,
+    scriptOptions: {
+      use() {
+        return { ttq: window.ttq }
+      },
+    },
+    clientInit: import.meta.server
+      ? undefined
+      : () => {
+          const ttq: TikTokPixelApi['ttq'] = window.ttq = function (...params: any[]) {
+            // @ts-expect-error untyped
+            if (ttq.callMethod) {
+              // @ts-expect-error untyped
+              ttq.callMethod(...params)
+            }
+            else {
+              ttq.queue.push(params)
+            }
+          } as any
+          ttq.push = ttq
+          ttq.loaded = true
+          ttq.queue = []
+          ttq('init', options?.id)
+          if (options?.trackPageView !== false) {
+            ttq('page')
+          }
+        },
+  }), _options)
+}

src/runtime/types.ts

@@ -31,6 +31,7 @@ import type { UmamiAnalyticsInput } from './registry/umami-analytics'
 import type { RybbitAnalyticsInput } from './registry/rybbit-analytics'
 import type { RedditPixelInput } from './registry/reddit-pixel'
 import type { PayPalInput } from './registry/paypal'
+import type { TikTokPixelInput } from './registry/tiktok-pixel'
 import { object } from '#nuxt-scripts-validator'
 
 export type WarmupStrategy = false | 'preload' | 'preconnect' | 'dns-prefetch'
@@ -152,6 +153,7 @@ export interface ScriptRegistry {
   redditPixel?: RedditPixelInput
   segment?: SegmentInput
   stripe?: StripeInput
+  tiktokPixel?: TikTokPixelInput
   xPixel?: XPixelInput
   snapchatPixel?: SnapTrPixelInput
   youtubePlayer?: YouTubePlayerInput