DYDouyin setup

Overview

adscapi posts server-side conversion callbacks to Ocean Engine, the ad platform behind Douyin (抖音) and Toutiao (今日头条). This is the landing-page ("H5") 转化回传 (conversion callback) API. Attribution is entirely callback-keyed: every ad click lands on your page with a click token (clickid) in the URL. You capture that token, adscapi carries it as event.clickIds.clickid, and it is sent back as context.ad.callback when the visitor converts. Ocean Engine has no other way to match the conversion, so no hashed email/phone and no API secret are used — the callback token is the whole identity.

Prerequisites

• An Ocean Engine (巨量引擎) advertising account.
• An event asset ("事件资产") set up in Event Manager (事件管理).
• Your landing page must capture the click token from the ad URL macro __CLICKID__ and pass it into adscapi as clickIds.clickid on the conversion event.

1. Create an account

1. Go to https://www.oceanengine.com/ and register a 巨量引擎 advertiser account.
2. Open Event Manager at https://event-manager.oceanengine.com/.
3. Create a landing-page ("落地页/H5") event asset for your site.

2. Get your credentials

Ocean Engine's landing-page callback endpoint is unauthenticated — the click token you send in context.ad.callback both routes and attributes the event, so there is no API key to fetch. The only real setup is capturing that token on your page. adscapi still needs one opt-in switch, DOUYIN_ENABLED, so it never fans out to Ocean Engine for an account that has not turned the destination on.

3. Configure adscapi

export DOUYIN_ENABLED=1

Then make sure each conversion event carries the click token:

// on the landing page, read the clickid the ad appended to the URL, then later:
adscapi.track({
  name: 'purchase',
  value: 100,
  currency: 'CNY',
  clickIds: { clickid: capturedClickId },
  consent: { adUserData: true, adPersonalization: true },
});

Without clickIds.clickid (or without adPersonalization consent), the Douyin dispatcher no-ops — there is nothing to attribute.

4. Verify

adscapi verify --platform douyin

Douyin has no live credential check (there is no token to test); verification only confirms the platform is registered. Confirm real delivery in Event Manager's event debugging view (事件调试) after firing a test conversion with a valid click token.

5. Event mapping

adscapi's canonical events map to Ocean Engine's event_type values (from events.ts). Unmapped names pass through unchanged.

Troubleshooting

• Nothing arrives / event no-ops — the click token is missing. Confirm your landing page captured __CLICKID__ and passed it as clickIds.clickid, and that the visitor granted adPersonalization consent.
• HTTP 4xx — the callback token is expired or malformed, the timestamp is out of range, or the event_type is not one Ocean Engine recognizes. The timestamp field is UNIX epoch milliseconds, not seconds.
• Common gotcha — click tokens are short-lived. Fire the conversion callback soon after the click; a stale token will not match.