From 0069cf22aa91362759171b4b3403e4c52d1db5be Mon Sep 17 00:00:00 2001 From: laurentdav <45101601+laurentdav@users.noreply.github.com> Date: Tue, 17 Nov 2026 22:58:53 +0100 Subject: [PATCH] fix(tiktok): send the Events API 2.0 body The destination posted the Events API 1.0 body (pixel_code, context) to the 2.0 endpoint /open_api/v1.3/event/track/: TikTok recorded nothing. Now event_source/event_source_id, user/page per event, event_time in seconds, phone_number sent as phone, identity fields normalised before hashing. Fixes #768 Co-Authored-By: Claude Opus 5.5 --- .changeset/tiktok-events-api-2.md | 9 +++ .../tiktok/src/__tests__/hash.test.ts | 25 ++++++- .../tiktok/src/__tests__/index.test.ts | 35 ++++----- .../destinations/tiktok/src/examples/step.ts | 73 +++++++++---------- .../server/destinations/tiktok/src/hash.ts | 43 +++++++---- .../server/destinations/tiktok/src/push.ts | 46 +++--------- .../tiktok/src/schemas/settings.ts | 4 +- .../destinations/tiktok/src/types/index.ts | 29 +++----- website/docs/destinations/server/tiktok.mdx | 8 +- 9 files changed, 140 insertions(+), 132 deletions(-) create mode 100644 .changeset/tiktok-events-api-2.md diff --git a/.changeset/tiktok-events-api-2.md b/.changeset/tiktok-events-api-2.md new file mode 100644 index 000000000..aafb4500f --- /dev/null +++ b/.changeset/tiktok-events-api-2.md @@ -0,0 +1,9 @@ +--- +'@walkeros/server-destination-tiktok': patch +--- + +Send the Events API 2.0 body the `/open_api/v1.3/event/track/` endpoint expects +(`event_source`, `event_source_id`, and `user`, `page`, `event_time` in seconds +per event) instead of the 1.0 `pixel_code`/`context` body, which TikTok does not +record. `phone_number` is sent as `phone`; email, phone and external_id are +normalised before hashing. diff --git a/packages/server/destinations/tiktok/src/__tests__/hash.test.ts b/packages/server/destinations/tiktok/src/__tests__/hash.test.ts index 3f9d7468b..823911ca3 100644 --- a/packages/server/destinations/tiktok/src/__tests__/hash.test.ts +++ b/packages/server/destinations/tiktok/src/__tests__/hash.test.ts @@ -1,7 +1,7 @@ import { hashUserData } from '../hash'; describe('hashUserData', () => { - test('hashes email, phone_number, external_id', async () => { + test('hashes email, phone_number (sent as phone), external_id', async () => { const userData = { email: 'user@example.com', phone_number: '+14135552671', @@ -12,12 +12,13 @@ describe('hashUserData', () => { // All three fields should be hashed (not equal to original) expect(result.email).not.toBe(userData.email); - expect(result.phone_number).not.toBe(userData.phone_number); + expect(result.phone_number).toBeUndefined(); + expect(result.phone).not.toBe(userData.phone_number); expect(result.external_id).not.toBe(userData.external_id); // Should be SHA256 hex strings (64 chars) expect(result.email).toMatch(/^[a-f0-9]{64}$/); - expect(result.phone_number).toMatch(/^[a-f0-9]{64}$/); + expect(result.phone).toMatch(/^[a-f0-9]{64}$/); expect(result.external_id).toMatch(/^[a-f0-9]{64}$/); }); @@ -48,10 +49,26 @@ describe('hashUserData', () => { expect(result.email).toBe('user@example.com'); // phone_number and external_id should still be hashed - expect(result.phone_number).not.toBe('+14135552671'); + expect(result.phone).not.toBe('+14135552671'); expect(result.external_id).not.toBe('user-123'); }); + test('normalises before hashing and keeps existing digests', async () => { + const a = await hashUserData({ + email: ' User@Example.COM ', + phone: '+1 (413) 555-2671', + }); + const b = await hashUserData({ + email: 'user@example.com', + phone: '+14135552671', + }); + expect(a).toEqual(b); + + const digest = + 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514'; + expect(await hashUserData({ email: digest })).toEqual({ email: digest }); + }); + test('handles empty object', async () => { const result = await hashUserData({}); expect(result).toEqual({}); diff --git a/packages/server/destinations/tiktok/src/__tests__/index.test.ts b/packages/server/destinations/tiktok/src/__tests__/index.test.ts index b9d150c89..4dee90b0d 100644 --- a/packages/server/destinations/tiktok/src/__tests__/index.test.ts +++ b/packages/server/destinations/tiktok/src/__tests__/index.test.ts @@ -139,7 +139,7 @@ describe('Server Destination TikTok', () => { ); }); - test('body includes pixel_code, partner_name, data', async () => { + test('body is the Events API 2.0 format', async () => { const event = getEvent(); const config: Config = { settings: { accessToken, pixelCode, partner_name: 'walkerOS' }, @@ -155,12 +155,14 @@ describe('Server Destination TikTok', () => { ); const requestBody = JSON.parse(mockSendServer.mock.calls[0][1]); - expect(requestBody.pixel_code).toBe(pixelCode); + expect(requestBody.event_source).toBe('web'); + expect(requestBody.event_source_id).toBe(pixelCode); + expect(requestBody).not.toHaveProperty('pixel_code'); expect(requestBody.partner_name).toBe('walkerOS'); expect(requestBody.data).toHaveLength(1); }); - test('event data has event, event_id, timestamp', async () => { + test('event data has event, event_id, event_time in seconds', async () => { const event = getEvent('page view', { timestamp: 1700000900000 }); const config: Config = { settings: { accessToken, pixelCode }, @@ -179,7 +181,8 @@ describe('Server Destination TikTok', () => { const eventData = requestBody.data[0]; expect(eventData.event).toBe('page view'); expect(eventData.event_id).toBe(event.id); - expect(eventData.timestamp).toBe('2023-11-14T22:28:20.000Z'); + expect(eventData.event_time).toBe(1700000900); + expect(eventData).not.toHaveProperty('context'); }); test('test_event_code included when set', async () => { @@ -201,7 +204,7 @@ describe('Server Destination TikTok', () => { expect(requestBody.test_event_code).toBe('TEST12345'); }); - test('context.page.url from event.source.url', async () => { + test('page.url from event.source.url', async () => { const event = getEvent('page view', { source: { type: 'browser', @@ -223,9 +226,7 @@ describe('Server Destination TikTok', () => { ); const requestBody = JSON.parse(mockSendServer.mock.calls[0][1]); - expect(requestBody.data[0].context.page.url).toBe( - 'https://example.com/page', - ); + expect(requestBody.data[0].page.url).toBe('https://example.com/page'); }); test('user data is hashed', async () => { @@ -251,7 +252,7 @@ describe('Server Destination TikTok', () => { ); const requestBody = JSON.parse(mockSendServer.mock.calls[0][1]); - const userData = requestBody.data[0].context.user; + const userData = requestBody.data[0].user; expect(userData.email).toBeDefined(); // Should be hashed (64 hex chars) expect(userData.email).toMatch(/^[a-f0-9]{64}$/); @@ -272,7 +273,7 @@ describe('Server Destination TikTok', () => { ['email'], ); expect(result2.email).toBe('m@i.l'); - expect(result2.phone_number).toMatch(/^[a-f0-9]{64}$/); + expect(result2.phone).toMatch(/^[a-f0-9]{64}$/); }); test('environment customization', async () => { @@ -339,8 +340,8 @@ describe('Server Destination TikTok', () => { ingest, }), ); - expect(sent().data[0].context.ip).toBe('203.0.113.7'); - expect(sent().data[0].context.user_agent).toBeDefined(); + expect(sent().data[0].user?.ip).toBe('203.0.113.7'); + expect(sent().data[0].user?.user_agent).toBeDefined(); }); test('falls back to event.user.ip and userAgent', async () => { @@ -353,8 +354,8 @@ describe('Server Destination TikTok', () => { env: testEnv, }), ); - expect(sent().data[0].context.ip).toBe('198.51.100.2'); - expect(sent().data[0].context.user_agent).toBeDefined(); + expect(sent().data[0].user?.ip).toBe('198.51.100.2'); + expect(sent().data[0].user?.user_agent).toBeDefined(); }); test('sends neither when disabled with false', async () => { @@ -368,8 +369,8 @@ describe('Server Destination TikTok', () => { ingest, }), ); - expect(sent().data[0].context.ip).toBeUndefined(); - expect(sent().data[0].context.user_agent).toBeUndefined(); + expect(sent().data[0].user?.ip).toBeUndefined(); + expect(sent().data[0].user?.user_agent).toBeUndefined(); }); test('lets an explicit ip setting win over the default', async () => { @@ -383,7 +384,7 @@ describe('Server Destination TikTok', () => { ingest, }), ); - expect(sent().data[0].context.ip).toBe('10.0.0.1'); + expect(sent().data[0].user?.ip).toBe('10.0.0.1'); }); }); }); diff --git a/packages/server/destinations/tiktok/src/examples/step.ts b/packages/server/destinations/tiktok/src/examples/step.ts index 8b6fdddf5..2e2868cad 100644 --- a/packages/server/destinations/tiktok/src/examples/step.ts +++ b/packages/server/destinations/tiktok/src/examples/step.ts @@ -7,17 +7,18 @@ import { createEvent, getEvent } from '@walkeros/core'; * At push time, the destination calls * `env.sendServer(url, body, { headers })` where `url` is the fixed * TikTok Events API endpoint and `body` is the JSON-stringified payload - * `{ pixel_code, partner_name, data: [tiktokEvent] }`. + * `{ event_source, event_source_id, partner_name, data: [tiktokEvent] }` + * (Events API 2.0). * * The test fixture pins `accessToken = 's3cr3t'` and `pixelCode = 'PIXEL_CODE'`. * * Body fields are emitted in the order the destination constructs them * (insertion order matters for `JSON.stringify` string equality): - * pixel_code, partner_name, data[] with { event, event_id, timestamp, - * context: { user?, page }, properties }. + * event_source, event_source_id, partner_name, data[] with { event, + * event_time (seconds), event_id, user?, page?, properties }. * - * User identity fields (`email`, `phone_number`, `external_id`) are hashed - * with SHA-256. + * User identity fields (`email`, `phone`, `external_id`) are normalised and + * hashed with SHA-256; `phone_number` is sent as `phone`. */ const ENDPOINT = 'https://business-api.tiktok.com/open_api/v1.3/event/track/'; const HEADERS = { @@ -87,21 +88,20 @@ export const purchase: Flow.StepExample = { 'sendServer', ENDPOINT, JSON.stringify({ - pixel_code: 'PIXEL_CODE', + event_source: 'web', + event_source_id: 'PIXEL_CODE', partner_name: 'walkerOS', data: [ { event: 'Purchase', + event_time: 1700000900, event_id: 'd1e2f3a4b5c60001', - timestamp: '2023-11-14T22:28:20.000Z', - context: { - user: { - external_id: - 'fcdec6df4d44dbc637c7c5b58efface52a7f8a88535423430255be0bb89bedd8', - }, - page: { - url: 'https://shop.example.com/checkout/complete', - }, + user: { + external_id: + 'fcdec6df4d44dbc637c7c5b58efface52a7f8a88535423430255be0bb89bedd8', + }, + page: { + url: 'https://shop.example.com/checkout/complete', }, properties: { value: 249.99, @@ -188,17 +188,16 @@ export const addToCart: Flow.StepExample = { 'sendServer', ENDPOINT, JSON.stringify({ - pixel_code: 'PIXEL_CODE', + event_source: 'web', + event_source_id: 'PIXEL_CODE', partner_name: 'walkerOS', data: [ { event: 'AddToCart', + event_time: 1700000901, event_id: 'd1e2f3a4b5c60002', - timestamp: '2023-11-14T22:28:21.000Z', - context: { - page: { - url: 'https://shop.example.com/products/running-shoes', - }, + page: { + url: 'https://shop.example.com/products/running-shoes', }, properties: { content_type: 'product', @@ -240,17 +239,16 @@ export const pageView: Flow.StepExample = { 'sendServer', ENDPOINT, JSON.stringify({ - pixel_code: 'PIXEL_CODE', + event_source: 'web', + event_source_id: 'PIXEL_CODE', partner_name: 'walkerOS', data: [ { event: 'page view', + event_time: 1700000902, event_id: 'd1e2f3a4b5c60003', - timestamp: '2023-11-14T22:28:22.000Z', - context: { - page: { - url: 'https://example.com/docs/', - }, + page: { + url: 'https://example.com/docs/', }, properties: {}, }, @@ -294,22 +292,21 @@ export const lead: Flow.StepExample = { 'sendServer', ENDPOINT, JSON.stringify({ - pixel_code: 'PIXEL_CODE', + event_source: 'web', + event_source_id: 'PIXEL_CODE', partner_name: 'walkerOS', data: [ { event: 'SubmitForm', + event_time: 1700000903, event_id: 'd1e2f3a4b5c60004', - timestamp: '2023-11-14T22:28:23.000Z', - context: { - user: { - // sha256('user@example.com') - email: - 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514', - }, - page: { - url: 'https://example.com/contact', - }, + user: { + // sha256('user@example.com') + email: + 'b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514', + }, + page: { + url: 'https://example.com/contact', }, properties: {}, }, diff --git a/packages/server/destinations/tiktok/src/hash.ts b/packages/server/destinations/tiktok/src/hash.ts index d7bd7664e..df5433382 100644 --- a/packages/server/destinations/tiktok/src/hash.ts +++ b/packages/server/destinations/tiktok/src/hash.ts @@ -1,25 +1,38 @@ import type { UserData } from './types'; import { getHashServer } from '@walkeros/server-core'; -const keysToHash = ['email', 'phone_number', 'external_id']; +const SHA256_HEX = /^[a-f0-9]{64}$/; -function shouldBeHashed(key: string, doNotHash: string[] = []): boolean { - return keysToHash.includes(key) && !doNotHash.includes(key); -} +// Normalised as TikTok expects before hashing. +const normalize: Record string> = { + email: (value) => value.trim().toLowerCase(), + phone: (value) => value.replace(/[^\d+]/g, ''), + external_id: (value) => value.trim(), +}; +/** + * Hashes email, phone and external_id with SHA-256 after normalisation. + * `phone_number` is renamed to `phone`, the Events API 2.0 key. An existing + * SHA-256 hex digest is kept as it is. + */ export async function hashUserData( userData: UserData, doNotHash: string[] = [], ): Promise { - const entries = await Promise.all( - Object.entries(userData).map(async ([key, value]) => { - if (value === undefined) return [key, value]; - if (shouldBeHashed(key, doNotHash)) { - return [key, await getHashServer(String(value))]; - } - return [key, value]; - }), - ); - - return Object.fromEntries(entries) as UserData; + const result: Record = {}; + for (const [rawKey, value] of Object.entries(userData)) { + if (value === undefined || value === null || value === '') continue; + const key = rawKey === 'phone_number' ? 'phone' : rawKey; + const normalizer = normalize[key]; + const skip = doNotHash.includes(rawKey) || doNotHash.includes(key); + if (!normalizer || skip) { + result[key] = value; + continue; + } + const normalized = normalizer(String(value)); + result[key] = SHA256_HEX.test(normalized) + ? normalized + : await getHashServer(normalized); + } + return result as UserData; } diff --git a/packages/server/destinations/tiktok/src/push.ts b/packages/server/destinations/tiktok/src/push.ts index 0750ba0bc..3f0f9b3d8 100644 --- a/packages/server/destinations/tiktok/src/push.ts +++ b/packages/server/destinations/tiktok/src/push.ts @@ -1,11 +1,4 @@ -import type { - EventData, - EventContext, - PushFn, - RequestBody, - UserData, - Env, -} from './types'; +import type { EventData, PushFn, RequestBody, UserData, Env } from './types'; import type { Collector, Mapping as WalkerOSMapping } from '@walkeros/core'; import { createMappingRoot, @@ -71,13 +64,8 @@ const send: PushFn = async function ( } } - // Hash identity fields - const hashedUserData = await hashUserData(userData, doNotHash); - - // Build context - const context: EventContext = {}; - - // Client IP and user agent auto-fill + // Hash identity fields, then add the client IP and user agent in clear + const user = await hashUserData(userData, doNotHash); const root = createMappingRoot(ingest, event); const clientIp = await resolveClient(ip, DEFAULT_IP, root, collector); const clientUserAgent = await resolveClient( @@ -86,36 +74,26 @@ const send: PushFn = async function ( root, collector, ); - if (clientIp !== undefined) context.ip = clientIp; - if (clientUserAgent !== undefined) context.user_agent = clientUserAgent; - - // Add user data if non-empty - if (Object.keys(hashedUserData).length > 0) { - context.user = hashedUserData; - } + if (clientIp !== undefined) user.ip = clientIp; + if (clientUserAgent !== undefined) user.user_agent = clientUserAgent; - // Page context from event source - context.page = { - url: event.source?.url, - }; - - // Build event data + // Events API 2.0 item: user, page and properties per event const tiktokEvent: EventData = { event: event.name, + event_time: Math.round((event.timestamp || Date.now()) / 1000), event_id: event.id, - timestamp: new Date(event.timestamp).toISOString(), - context, + ...(Object.keys(user).length > 0 ? { user } : {}), + ...(event.source?.url ? { page: { url: event.source.url } } : {}), properties, }; - // Build request body const body: RequestBody = { - pixel_code: pixelCode, - partner_name, + event_source: 'web', + event_source_id: pixelCode, + ...(partner_name ? { partner_name } : {}), data: [tiktokEvent], }; - // Test event code if (test_event_code) body.test_event_code = test_event_code; logger.debug('Calling TikTok Events API', { diff --git a/packages/server/destinations/tiktok/src/schemas/settings.ts b/packages/server/destinations/tiktok/src/schemas/settings.ts index a300b75ac..6a81f3ae0 100644 --- a/packages/server/destinations/tiktok/src/schemas/settings.ts +++ b/packages/server/destinations/tiktok/src/schemas/settings.ts @@ -37,10 +37,10 @@ export const SettingsSchema = z .describe('Partner name for TikTok attribution (default walkerOS)') .optional(), ip: InputSchema.describe( - 'Client IP, sent as context.ip. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off.', + 'Client IP, sent as user.ip. Resolves against { ingest, event }. Default: ["ingest.ip", "event.user.ip"]. false switches it off.', ).optional(), userAgent: InputSchema.describe( - 'Client user agent, sent as context.user_agent. Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off.', + 'Client user agent, sent as user.user_agent. Resolves against { ingest, event }. Default: ["ingest.userAgent", "event.user.userAgent"]. false switches it off.', ).optional(), }) .strict(); diff --git a/packages/server/destinations/tiktok/src/types/index.ts b/packages/server/destinations/tiktok/src/types/index.ts index 3d9e9e48c..6fe47e896 100644 --- a/packages/server/destinations/tiktok/src/types/index.ts +++ b/packages/server/destinations/tiktok/src/types/index.ts @@ -54,9 +54,10 @@ export type PushEvents = DestinationServer.PushEvents; export type Rule = WalkerOSMapping.Rule; export type Rules = WalkerOSMapping.Rules; -// TikTok Events API Request Body +// TikTok Events API 2.0 request body (POST /open_api/v1.3/event/track/) export interface RequestBody { - pixel_code: string; + event_source: 'web'; + event_source_id: string; partner_name?: string; test_event_code?: string; data: EventData[]; @@ -66,28 +67,25 @@ export interface RequestBody { export interface EventData { event: string; event_id: string; - timestamp: string; - context?: EventContext; - properties?: Record; -} - -// Context object within each event -export interface EventContext { - ip?: string; - user_agent?: string; + /** Unix time in seconds */ + event_time: number; user?: UserData; page?: PageContext; - ad?: AdContext; + properties?: Record; } -// User identity fields +// User identity and client fields export interface UserData { email?: string; + /** Sent as `phone`; `phone_number` is accepted as a mapping key */ + phone?: string; phone_number?: string; external_id?: string; ttp?: string; ttclid?: string; locale?: string; + ip?: string; + user_agent?: string; } // Page context @@ -96,11 +94,6 @@ export interface PageContext { referrer?: string; } -// Ad attribution context -export interface AdContext { - callback?: string; -} - // TikTok API response export interface ResponseBody { code: number; diff --git a/website/docs/destinations/server/tiktok.mdx b/website/docs/destinations/server/tiktok.mdx index 32be9ada6..50aaa2a54 100644 --- a/website/docs/destinations/server/tiktok.mdx +++ b/website/docs/destinations/server/tiktok.mdx @@ -22,7 +22,7 @@ Server-side event delivery to TikTok's Events API for enhanced conversion tracki flowMap={{ destinations: { default: { label: 'Destination', text: 'TikTok Events API', highlight: true } }, }} - post={<>Sends events server-side to TikTok's Events API using raw HTTP (no SDK). Identity fields (email, phone_number, external_id) are SHA-256 hashed, as mapped, before sending. Events include a stable `event_id` for deduplication with the browser pixel.} + post={<>Sends events server-side to TikTok's Events API using raw HTTP (no SDK). Requests use the Events API 2.0 format (`event_source: "web"`, `event_source_id` = pixel code, `user`, `page` and `properties` per event, `event_time` in seconds). Identity fields (email, phone, external_id) are normalised and SHA-256 hashed before sending. Events include a stable `event_id` for deduplication with the browser pixel.} /> ## Installation @@ -37,7 +37,7 @@ TikTok can answer HTTP 200 with a non-zero `code` in the body. That counts as a ## Client IP and user agent -The destination sends the client IP as `context.ip` and the user agent as `context.user_agent` by default. The `ip` and `userAgent` settings resolve against `{ ingest, event }` and default to `["ingest.ip", "event.user.ip"]` and `["ingest.userAgent", "event.user.userAgent"]`, so they fill in whenever the source provides them (see the `config.ingest` recipe on the [Express source](/docs/sources/server/express#ingest-metadata)). A value that resolves to nothing is not sent. Set either setting to `false` to turn it off, or to another mapping value to read it elsewhere. +The destination sends the client IP as `user.ip` and the user agent as `user.user_agent` by default. The `ip` and `userAgent` settings resolve against `{ ingest, event }` and default to `["ingest.ip", "event.user.ip"]` and `["ingest.userAgent", "event.user.userAgent"]`, so they fill in whenever the source provides them (see the `config.ingest` recipe on the [Express source](/docs/sources/server/express#ingest-metadata)). A value that resolves to nothing is not sent. Set either setting to `false` to turn it off, or to another mapping value to read it elsewhere. ## Consent @@ -45,9 +45,9 @@ The quickstart sets no `config.consent`, so TikTok receives every event, whateve ## Hashing -The destination SHA-256 hashes three `user_data` keys before sending: `email`, `phone_number` and `external_id`. Map personal data only to these keys, in `settings.user_data`, or under `user_data` in a rule's `data` or the destination's `config.data`. +The destination SHA-256 hashes three `user_data` keys before sending: `email` (trimmed, lowercased), `phone_number` or `phone` (digits and `+` only, sent as `phone`) and `external_id` (trimmed). A value that already is a SHA-256 hex digest is sent as it is. Map personal data only to these keys, in `settings.user_data`, or under `user_data` in a rule's `data` or the destination's `config.data`. -- **Every other key is sent in clear text.** Nothing checks the key names under `user_data`, so `phone` instead of `phone_number`, or `em` instead of `email`, reaches TikTok unhashed. Keys mapped outside `user_data` are sent in `properties`, unhashed. +- **Every other key is sent in clear text.** Nothing checks the key names under `user_data`, so `em` instead of `email`, reaches TikTok unhashed. Keys mapped outside `user_data` are sent in `properties`, unhashed. - **Values are hashed exactly as mapped**, without normalization. Normalize them upstream in the format TikTok expects, for example the email trimmed and lowercased. - **Map one value per key.** A list is joined with commas and hashed as one string.