Skip to content

fix(tiktokPixel): missing types#773

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
harlan-zw merged 2 commits into from
May 14, 2026
Merged

fix(tiktokPixel): missing types #773

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1252e7
feat(tiktokPixel): support event_id options on track + add missing st…
harlan-zw May 14, 2026
d72ebcb
test(tiktokPixel): add type assertions for ttq overload + standard ev…
harlan-zw May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 9 additions & 1 deletion packages/script/src/runtime/registry/tiktok-pixel.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -13,11 +13,13 @@ type StandardEvents
| 'AddPaymentInfo'
| 'CompletePayment'
| 'PlaceAnOrder'
| 'Purchase'

@coderabbitaicoderabbitaiBotMay 14, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

TikTok Pixel standard events list 2024 2025

💡 Result:

TikTok Pixel standard events list (the set of predefined web standard events you can send via TikTok Pixel / Events API) is not broken out by year (2024 vs 2025). The authoritative source is TikTok’s “Standard Events and Parameters” page, which lists the standard event names TikTok supports and is updated over time. As of TikTok’s latest help content, the supported standard event names include: ViewContent, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, CompletePayment, Purchase (alias/mapped to CompletePayment in reserved-event mapping), PlaceAnOrder, Subscribe, Download, Search, Contact, SubmitForm, CompleteRegistration, and ApplicationApproval. [1][2][3] Note: There is also a separate “reserved events” list that maps certain reserved event names to standard events (e.g., AddBilling → AddPaymentInfo; Checkout → PlaceAnOrder/InitiateCheckout mappings; Registration → CompleteRegistration; Browse → ViewContent; etc.). You should not use reserved event names as custom events because TikTok automatically maps them to standard events. [3] Sources: TikTok Ads Manager help, “Standard Events and Parameters” and “About reserved events” pages. [1][3]

Citations:

Remove 'StartTrial' from StandardEvents union—it is not in TikTok's official standard events list.

TikTok's official documentation lists these standard events: ViewContent, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, CompletePayment, Purchase, PlaceAnOrder, Subscribe, Download, Search, Contact, SubmitForm, CompleteRegistration, and ApplicationApproval. 'Purchase' is confirmed valid, but 'StartTrial' does not appear in the official Pixel API documentation and should not be included as a standard event unless it is explicitly mapped or documented by TikTok's API contract.

Also applies to: 22-22

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/script/src/runtime/registry/tiktok-pixel.ts` at line 16, The
StandardEvents union in tiktok-pixel.ts includes an invalid member 'StartTrial'
that is not part of TikTok's official Pixel standard events; remove 'StartTrial'
from the StandardEvents type (and any occurrences where it is used/mapped) so
the union only contains documented events like ViewContent, AddToCart,
InitiateCheckout, Purchase, etc.; update related enums or mappings that
reference 'StartTrial' (search for StandardEvents and any mapping
functions/classes in this file) to avoid dangling references.

| 'Contact'
| 'Download'
| 'SubmitForm'
| 'CompleteRegistration'
| 'Subscribe'
| 'StartTrial'

interface EventProperties {
content_id?: string
Expand All@@ -37,8 +39,14 @@ interface IdentifyProperties {
external_id?: string
}

interface TrackOptions {
/** Used to deduplicate events sent from both the browser Pixel and the server-side Events API. */
event_id?: string
[key: string]: any
}

type TtqFns
= ((cmd: 'track', event: StandardEvents | (string & {}), properties?: EventProperties) => void)
= ((cmd: 'track', event: StandardEvents | (string & {}), properties?: EventProperties, options?: TrackOptions) => void)
& ((cmd: 'page') => void)
& ((cmd: 'identify', properties: IdentifyProperties) => void)
& ((cmd: (string & {}), ...args: any[]) => void)
Expand Down
18 changes: 18 additions & 0 deletions test/types/types.test-d.ts
View file
Open in desktop
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
import type { ModuleOptions } from '../../packages/script/src/module'
import type { CrispApi } from '../../packages/script/src/runtime/registry/crisp'
import type { DefaultEventName } from '../../packages/script/src/runtime/registry/google-analytics'
import type { TikTokPixelApi } from '../../packages/script/src/runtime/registry/tiktok-pixel'
import type { NuxtConfigScriptRegistry, NuxtConfigScriptRegistryEntry, NuxtUseScriptOptions, RegistryScriptInput, ScriptRegistry, UseScriptContext } from '../../packages/script/src/runtime/types'
import { describe, expectTypeOf, it } from 'vitest'

Expand DownExpand Up@@ -157,3 +158,20 @@ describe('#nuxt-scripts/types exports', () => {
expectTypeOf<ScriptRegistry>().toHaveProperty('clarity')
})
})

describe('tiktok pixel ttq', () => {
type Ttq = TikTokPixelApi['ttq']

it('track accepts the 4th options arg with event_id', () => {
expectTypeOf<Ttq>().toBeCallableWith('track', 'Purchase', { value: 10 }, { event_id: 'abc' })
})

it('track accepts standard events including Purchase and StartTrial', () => {
expectTypeOf<Ttq>().toBeCallableWith('track', 'Purchase')
expectTypeOf<Ttq>().toBeCallableWith('track', 'StartTrial')
})

it('track still accepts arbitrary custom event names', () => {
expectTypeOf<Ttq>().toBeCallableWith('track', 'CustomEvent')
})
})
Loading