Skip to content
adscapi
← Platforms
Real Conversions API

Kuaishou setup

Set Kuaishou’s tokens once. Then every ads.conversions.track() call fans the event out to Kuaishou server-side — no per-platform code.

Setup guide

Overview

adscapi reports conversions to Kuaishou's callback API (转化回传), GET https://ad.partner.gifshow.com/track/activate. This is a callback-keyed integration, not a hashed-PII one. At click time Kuaishou fills the __CALLBACK__ macro on your tracking link with a per-click, encoded token. You capture that token and pass it back on the conversion; adscapi sends it as the callback query param. That token is the credential — the endpoint itself takes no account token. A report succeeds only when the JSON response is {"result":1}.

Prerequisites

  • A Kuaishou 磁力 (Magnetic) advertising account, authorized on the open platform (open.kuaishou.com).
  • A tracking / monitoring link on your ad that includes the __CALLBACK__ macro, so each click delivers a callback token to your landing page.

1. Create an account

  1. Register and get authorized on the Kuaishou marketing open platform at open.kuaishou.com.
  2. In the 磁力 ad platform, set your ad's monitoring URL to include callback=__CALLBACK__. Kuaishou replaces __CALLBACK__ with an encoded per-click token at delivery time.

2. Get your credentials

Secret Where to get it
KUAISHOU_EVENT_API_TOKEN Your 磁力 open-platform authorization token. adscapi uses it as the account enable-gate for Kuaishou dispatch; it is not sent to track/activate (that call authenticates per-click via the callback token).

Capture the click callback token on your landing page and forward it to your server. Pass it on the event as clickIds.callback. adscapi no-ops if it is absent (no click, nothing to report).

3. Configure adscapi

export KUAISHOU_EVENT_API_TOKEN="…"   # 磁力 open-platform authorization (enable-gate)

Send the per-click callback token on each event:

{ "name": "purchase", "value": 10.88, "clickIds": { "callback": "<__CALLBACK__ token>" } }

4. Verify

adscapi verify --platform kuaishou

Fire a test purchase with a real callback token and confirm the conversion appears in your 磁力 report. A response other than {"result":1} is a failure — see Troubleshooting.

5. Event mapping

adscapi maps its canonical events to Kuaishou's integer event_type. Only doc-confirmed types are mapped; an unknown non-numeric name is skipped (never sent with a guessed code). To report a type adscapi does not map, pass the integer directly as the event name (e.g. name: "7" for 1-day retention).

Canonical Kuaishou event_type Meaning
purchase 3 付费 Payment
lead 44 有效线索 Valid Lead
signup 2 注册 Registration

Payment-family types (3, 12, 13, 14, 15) also carry purchase_amount (yuan, two decimals), built from the event value.

Troubleshooting

  • result is not 1 — the callback token is expired, malformed, or already used, or the event_time is out of range. Kuaishou returns a JSON body; adscapi throws with it attached. Re-capture a fresh __CALLBACK__ token from a recent click.
  • Nothing is sent — adscapi no-ops when the callback token is missing (clickIds.callback) or when KUAISHOU_EVENT_API_TOKEN is unset. Wire the __CALLBACK__ capture on your landing page.
  • event_time — Kuaishou wants a 13-digit millisecond timestamp. adscapi converts its epoch-seconds eventTime for you; send seconds, not milliseconds.
  • Wrong-channel attribution — Kuaishou supports &is_direct_match=false for conversions attributed elsewhere. adscapi does not send it; open an issue if you need it.

1. Install adscapi

shell
npm install adscapi
# or run without installing:
npx adscapi platforms

2. Get Kuaishou's tokens

Kuaishou activates once all of these are set. Run npx adscapi platforms to see them, then get each value from Kuaishou’s ads or events dashboard.

KUAISHOU_EVENT_API_TOKEN

3. Set them for adscapi

Export the tokens in the environment that runs your server or the adscapi CLI.

shell
export KUAISHOU_EVENT_API_TOKEN="…"

4. Verify

check confirms the secrets are present; verify calls Kuaishou’s API to confirm they are valid.

shell
npx adscapi check
npx adscapi verify --platform kuaishou

5. Track a conversion

One call, sent to Kuaishou and every other configured platform. Pass raw email — adscapi hashes per platform. Consent is required.

ts
import { createAdscapi } from 'adscapi';

const ads = createAdscapi();

const results = await ads.conversions.track({
  name: 'purchase',
  value: 49,
  currency: 'USD',
  user: { email: 'buyer@example.com' },
  consent: { adUserData: true, adPersonalization: true },
});

See the exact request on the Kuaishou payload preview.