fix(tiktok-pixel): use TikTok's array snippet protocol (#786)

Author: harlan-zw

package.json

@@ -19,7 +19,7 @@
 "dev": "nuxt dev playground",
 "dev:ssl": "nuxt dev playground --https",
 "dev:prepare": "pnpm -r dev:prepare && nuxt prepare && nuxt prepare playground && pnpm prepare:fixtures",
-"prepare:fixtures": "nuxt prepare test/fixtures/basic && nuxt prepare test/fixtures/cdn && nuxt prepare test/fixtures/extend-registry && nuxt prepare test/fixtures/partytown && nuxt prepare test/fixtures/first-party && nuxt prepare test/fixtures/linkedin-insight && nuxt prepare test/fixtures/linkedin-insight-cdn && nuxt prepare test/fixtures/calendly && nuxt prepare test/fixtures/calendly-cdn && nuxt prepare test/fixtures/ahrefs-analytics && nuxt prepare test/fixtures/ahrefs-analytics-cdn && nuxt prepare test/fixtures/usercentrics",
+"prepare:fixtures": "nuxt prepare test/fixtures/basic && nuxt prepare test/fixtures/cdn && nuxt prepare test/fixtures/extend-registry && nuxt prepare test/fixtures/partytown && nuxt prepare test/fixtures/first-party && nuxt prepare test/fixtures/linkedin-insight && nuxt prepare test/fixtures/linkedin-insight-cdn && nuxt prepare test/fixtures/tiktok-pixel && nuxt prepare test/fixtures/calendly && nuxt prepare test/fixtures/calendly-cdn && nuxt prepare test/fixtures/ahrefs-analytics && nuxt prepare test/fixtures/ahrefs-analytics-cdn && nuxt prepare test/fixtures/usercentrics",
 "typecheck": "nuxt typecheck",
 "release": "pnpm build && bumpp -r --output=CHANGELOG.md",
 "lint": "eslint .",

packages/script/src/registry-types.json

@@ -1015,14 +1015,29 @@
 "code": "interface TrackOptions {\n /** Used to deduplicate events sent from both the browser Pixel and the server-side Events API. */\n event_id?: string\n /**\n * Sandbox test-event identifier. When set, events route to TikTok's Test Events panel\n * without affecting production reporting.\n */\n test_event_code?: string\n [key: string]: any\n}"
  },
  {
-"name": "TtqFns",
+"name": "TtqInstance",
+"kind": "interface",
+"code": "export interface TtqInstance {\n /** Track a page view. */\n page: () => void\n /** Track a standard or custom conversion event. */\n track: (event: StandardEvents | (string & {}), properties?: EventProperties, options?: TrackOptions) => void\n /** Associate advanced-matching identifiers with the current user. */\n identify: (properties: IdentifyProperties) => void\n /** Opt user in to tracking. Queued before the script loads; live once `events.js` binds. */\n grantConsent: () => void\n /** Opt user out of tracking. Queued before the script loads; live once `events.js` binds. */\n revokeConsent: () => void\n /** Defer consent until an explicit grant/revoke. Queued before the script loads; live once `events.js` binds. */\n holdConsent: () => void\n enableCookie: () => void\n disableCookie: () => void\n}"
+ },
+ {
+"name": "TtqCallable",
 "kind": "type",
-"code": "type TtqFns\n = ((cmd: 'track', event: StandardEvents | (string & {}), properties?: EventProperties, options?: TrackOptions) => void)\n & ((cmd: 'page') => void)\n & ((cmd: 'identify', properties: IdentifyProperties) => void)\n & ((cmd: (string & {}), ...args: any[]) => void)"
+"code": "type TtqCallable\n = ((cmd: 'track', event: StandardEvents | (string & {}), properties?: EventProperties, options?: TrackOptions) => void)\n & ((cmd: 'page') => void)\n & ((cmd: 'identify', properties: IdentifyProperties) => void)\n & ((cmd: (string & {}), ...args: any[]) => void)"
+ },
+ {
+"name": "Ttq",
+"kind": "type",
+"code": "export type Ttq = TtqCallable & TtqInstance & {\n /** Resolve the per-pixel method bag for a specific pixel id. */\n instance: (id: string) => TtqInstance\n}"
  },
  {
 "name": "TikTokPixelApi",
 "kind": "interface",
-"code": "export interface TikTokPixelApi {\n ttq: TtqFns & {\n push: TtqFns\n loaded: boolean\n queue: any[]\n /** Opt user in to tracking. Queued before the script loads; live once `events.js` binds. */\n grantConsent: () => void\n /** Opt user out of tracking. Queued before the script loads; live once `events.js` binds. */\n revokeConsent: () => void\n /** Defer consent until an explicit grant/revoke. Queued before the script loads; live once `events.js` binds. */\n holdConsent: () => void\n }\n}"
+"code": "export interface TikTokPixelApi {\n ttq: Ttq\n}"
+ },
+ {
+"name": "TtqArray",
+"kind": "type",
+"code": "type TtqArray = TtqInstance & Array<any[]> & {\n methods: string[]\n setAndDefer: (target: any, method: string) => void\n instance: (id: string) => TtqInstance\n _i?: Record<string, any[]>\n _t?: Record<string, number>\n _o?: Record<string, any>\n}"
  },
  {
 "name": "TikTokPixelOptions",

packages/script/src/runtime/registry/tiktok-pixel.ts

@@ -70,28 +70,70 @@ interface TrackOptions {
 [key: string]: any
 }
 
-typeTtqFns
+/**
+ * The deferred methods TikTok's base code installs on `ttq`. Calling one before
+ * `events.js` loads pushes a `[method, ...args]` tuple onto the queue; afterwards
+ * `events.js` rebinds them to live implementations.
+ */
+exportinterfaceTtqInstance{
+/** Track a page view. */
+page: ()=>void
+/** Track a standard or custom conversion event. */
+track: (event: StandardEvents|(string&{}),properties?: EventProperties,options?: TrackOptions)=>void
+/** Associate advanced-matching identifiers with the current user. */
+identify: (properties: IdentifyProperties)=>void
+/** Opt user in to tracking. Queued before the script loads; live once `events.js` binds. */
+grantConsent: ()=>void
+/** Opt user out of tracking. Queued before the script loads; live once `events.js` binds. */
+revokeConsent: ()=>void
+/** Defer consent until an explicit grant/revoke. Queued before the script loads; live once `events.js` binds. */
+holdConsent: ()=>void
+enableCookie: ()=>void
+disableCookie: ()=>void
+}
+
+/**
+ * Legacy callable signature. Pre-1.2 `useScriptTikTokPixel` exposed `ttq` as an
+ * `fbq`-style callable (`ttq('page')`, `ttq('track', …)`); the adapter keeps it
+ * working alongside the method form.
+ */
+typeTtqCallable
 =((cmd: 'track',event: StandardEvents|(string&{}),properties?: EventProperties,options?: TrackOptions)=>void)
 &((cmd: 'page')=>void)
 &((cmd: 'identify',properties: IdentifyProperties)=>void)
 &((cmd: (string&{}), ...args: any[])=>void)
 
+/**
+ * The public `ttq` returned by the composable: a callable adapter (legacy form)
+ * that also carries the deferred methods (`ttq.page()`, `ttq.track(…)`). The
+ * adapter forwards to `window.ttq`, which is TikTok's real array protocol.
+ */
+exporttypeTtq=TtqCallable&TtqInstance&{
+/** Resolve the per-pixel method bag for a specific pixel id. */
+instance: (id: string)=>TtqInstance
+}
+
 exportinterfaceTikTokPixelApi{
-ttq: TtqFns&{
-push: TtqFns
-loaded: boolean
-queue: any[]
-/** Opt user in to tracking. Queued before the script loads; live once `events.js` binds. */
-grantConsent: ()=>void
-/** Opt user out of tracking. Queued before the script loads; live once `events.js` binds. */
-revokeConsent: ()=>void
-/** Defer consent until an explicit grant/revoke. Queued before the script loads; live once `events.js` binds. */
-holdConsent: ()=>void
-}
+ttq: Ttq
+}
+
+/**
+ * TikTok's `window.ttq` is an Array, not a callable: `events.js` reads it as a
+ * queue of `[method, ...args]` tuples and replays them, with the deferred
+ * methods installed as own properties on the array.
+ */
+typeTtqArray=TtqInstance&Array<any[]>&{
+methods: string[]
+setAndDefer: (target: any,method: string)=>void
+instance: (id: string)=>TtqInstance
+_i?: Record<string,any[]>
+_t?: Record<string,number>
+_o?: Record<string,any>
 }
 
 declare global {
-interfaceWindowextendsTikTokPixelApi{
+interfaceWindow{
+ttq: TtqArray
 TiktokAnalyticsObject: string
 }
 }
@@ -107,6 +149,9 @@ export function tiktokPixelSrc(region?: 'global' | 'us'): string {
  : 'https://analytics.tiktok.com/i18n/pixel/events.js'
 }
 
+// The deferred-method names TikTok's base code defers onto `ttq`.
+constTTQ_METHODS=['page','track','identify','instances','debug','on','off','once','ready','alias','group','enableCookie','disableCookie','holdConsent','revokeConsent','grantConsent']
+
 constSHA256_HEX=/^[a-f0-9]{64}$/i
 
 functionwarnUnhashedIdentify(props: Record<string,unknown>): void{
@@ -120,6 +165,23 @@ function warnUnhashedIdentify(props: Record<string, unknown>): void {
 }
 }
 
+/**
+ * Build the callable adapter returned to consumers. It dispatches to the live
+ * `window.ttq` array on every call, so it tracks `events.js` rebinding the
+ * deferred methods. Supports both `ttq('page')` (legacy) and `ttq.page()`.
+ */
+functioncreateTtqAdapter(): Ttq{
+constdispatch=(method: string, ...args: any[])=>{
+if(import.meta.dev&&method==='identify'&&args[0])
+warnUnhashedIdentify(args[0])
+return(window.ttqasany)[method]?.(...args)
+}
+constadapter=((method: string, ...args: any[])=>dispatch(method, ...args))asTtq
+for(constmethodof[...TTQ_METHODS,'instance'])
+(adapterasany)[method]=(...args: any[])=>dispatch(method, ...args)
+returnadapter
+}
+
 exportinterfaceTikTokPixelConsent{
 /** Call `ttq.grantConsent()`. */
 grant: ()=>void
@@ -141,47 +203,51 @@ export function useScriptTikTokPixel<T extends TikTokPixelApi>(_options?: TikTok
 schema: import.meta.dev ? TikTokPixelOptions : undefined,
 scriptOptions: {
 use(){
-return{ttq: window.ttq}
+return{ttq: createTtqAdapter()}
 },
 },
+// TikTok's `events.js` consumes the official array-based snippet protocol:
+// `window.ttq` is an Array of `[method, ...args]` tuples that `events.js`
+// drains once loaded. (It does NOT understand the Facebook `fbq` callable
+// protocol — using that shape silently drops every browser Pixel event.)
 clientInit: import.meta.server
  ? undefined
  : ()=>{
 window.TiktokAnalyticsObject='ttq'
-constttq: TikTokPixelApi['ttq']=window.ttq=function(...params: any[]){
-if(import.meta.dev&&params[0]==='identify'&&params[1])
-warnUnhashedIdentify(params[1])
-// @ts-expect-error untyped
-if(ttq.callMethod){
-// @ts-expect-error untyped
-ttq.callMethod(...params)
-}
-else{
-ttq.queue.push(params)
-}
-}asany
-ttq.push=ttq
-ttq.loaded=true
-ttq.queue=[]
-// Queue consent stubs so pre-load `ttq.grantConsent()` / `ttq.revokeConsent()` work.
-// The real events.js replaces these with live bindings once loaded.
-constconsentMethods=['grantConsent','revokeConsent','holdConsent']asconst
-for(constnameofconsentMethods){
-;(ttqasany)[name]=function(...params: any[]){
-ttq.queue.push([name, ...params])
+constttq=(window.ttq=window.ttq||([]asunknownasTtqArray))
+ttq.methods=TTQ_METHODS
+ttq.setAndDefer=function(target: any,method: string){
+target[method]=function(...args: any[]){
+target.push([method, ...args])
 }
 }
-if(options?.defaultConsent==='granted')
-ttq.grantConsent()
-elseif(options?.defaultConsent==='denied')
-ttq.revokeConsent()
-elseif(options?.defaultConsent==='hold')
-ttq.holdConsent()
+for(constmethodofttq.methods)
+ttq.setAndDefer(ttq,method)
+ttq.instance=function(id: string){
+constbag=ttq._i?.[id]||[]
+for(constmethodofttq.methods)
+ttq.setAndDefer(bag,method)
+returnbagasunknownasTtqInstance
+}
 if(options?.id){
-ttq('init',options.id)
-if(options?.trackPageView!==false){
-ttq('page')
-}
+// Per-pixel scaffolding read by `events.js` (equivalent to the base
+// code's `ttq.load(id)`, minus the <script> insertion that the
+// registry script tag already handles).
+ttq._i=ttq._i||{}
+ttq._i[options.id]=ttq._i[options.id]||[]
+;(ttq._i[options.id]asany)._u=tiktokPixelSrc(options?.region)
+ttq._t=ttq._t||{}
+ttq._t[options.id]=Date.now()
+ttq._o=ttq._o||{}
+ttq._o[options.id]={}
+if(options?.defaultConsent==='granted')
+ttq.grantConsent()
+elseif(options?.defaultConsent==='denied')
+ttq.revokeConsent()
+elseif(options?.defaultConsent==='hold')
+ttq.holdConsent()
+if(options?.trackPageView!==false)
+ttq.page()
 }
 },
 }),_options)asUseScriptContext<T,TikTokPixelConsent>