Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
9 changes: 9 additions & 0 deletions .changeset/tiktok-events-api-2.md
Original file line number Diff line number Diff line change
@@ -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.
25 changes: 21 additions & 4 deletions packages/server/destinations/tiktok/src/__tests__/hash.test.ts
Original file line number Diff line number Diff line change
@@ -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',
Expand All @@ -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}$/);
});

Expand Down Expand Up @@ -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({});
Expand Down
35 changes: 18 additions & 17 deletions packages/server/destinations/tiktok/src/__tests__/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand All @@ -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 },
Expand All @@ -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 () => {
Expand All @@ -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',
Expand All @@ -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 () => {
Expand All @@ -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}$/);
Expand All @@ -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 () => {
Expand Down Expand Up @@ -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 () => {
Expand All @@ -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 () => {
Expand All @@ -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 () => {
Expand All @@ -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');
});
});
});
73 changes: 35 additions & 38 deletions packages/server/destinations/tiktok/src/examples/step.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 = {
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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',
Expand Down Expand Up @@ -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: {},
},
Expand Down Expand Up @@ -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: {},
},
Expand Down
43 changes: 28 additions & 15 deletions packages/server/destinations/tiktok/src/hash.ts
Original file line number Diff line number Diff line change
@@ -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, (value: string) => 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<UserData> {
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<string, unknown> = {};
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;
}
Loading