pooriaarab Kuaishou Ads
Kuaishou has a documented mini-game advertising callback and a mini-program advertising-data query API. The fetched first-party sources do not establish a general web pixel, a general web or CRM Conversions API, or a general campaign- management API. Treat this skill as a mini-game and mini-program adapter. See Kuaishou's mini-game advertising guide and the mini-program advertising-data API.
The documented mini-game ad-account route is managed. The guide directs advertisers to a core agency or direct sales for account onboarding. It also requires registration as a Magnet Engine developer before the real-time ECPM report flow. The guide does not document self-serve signup for this mini-game route. See the account and onboarding section.
Use ad-conversion-hub for the canonical event, consent, identity, retry, and adapter rules. Pair it with ad-experiments for one-audience tests, seed sizing, PII-export authorization, and payment-provider truth.
Account and access
For the documented mini-game route, contact a core agency or direct sales,
register as a Magnet Engine developer, add an application, and obtain its
app_id, secret, and authorization link. Open the link and authorize one or
more ad accounts, or all accounts under the Kuaishou ID. Receive the one-time
auth_code at the callback address, exchange it below, and store the returned
tokens and advertiser ID on the server. See the authorization flow.
The guide says that the advertiser role can operate only on accounts under the registered or newly added business entity. Do not assume that a developer app can access an unrelated advertiser account. See Kuaishou's MAPI authorization guide.
Kuaishou documents these exact token operations for this route:
POST https://ad.e.kuaishou.com/rest/openapi/oauth2/authorize/access_token
POST https://ad.e.kuaishou.com/rest/openapi/oauth2/authorize/refresh_token
The guide documents auth_code as valid for 10 minutes and usable once, and
refresh_token as valid for 30 days. It uses inconsistent wording for the
access-token lifetime. Read the returned expiry and do not hard-code one day.
Each refresh returns a new pair and invalidates the old pair. Serialize refresh
operations per account and persist the new pair only after recording the
response, so two concurrent refreshes cannot invalidate each other's token or
leave a stale pair stored. See the token
instructions.
Use these local secret names. They are not Kuaishou parameter names:
KUAISHOU_AD_APP_ID, KUAISHOU_AD_APP_SECRET, KUAISHOU_AD_ACCESS_TOKEN,
KUAISHOU_AD_REFRESH_TOKEN, KUAISHOU_ADVERTISER_ID, and KUAISHOU_MINIAPP_ID.
Keep the application secret and tokens on the server. Do not put them in a browser bundle, URL, log, screenshot, or commit. These are hub security rules; the Kuaishou source defines the credentials and endpoints, not these local environment-variable names. See ad-conversion-hub security and Kuaishou's authorization guide.
Client-side mini-program attribution
No public Kuaishou browser tag or web pixel is documented in the first-party pages fetched for this skill. Do not add a guessed script URL, pixel ID, tag ID, cookie name, or browser event API. A website integration therefore remains first-party measurement only unless Kuaishou supplies a current product-specific contract. See the mini-game advertising guide and Kuaishou's public developer portal.
The documented client surface is a Kuaishou mini-game launch. In a commercial
advertising path, Kuaishou appends attribution data to the mini-program launch
query. The guide names ks.getLaunchOptionsSync as the API used to read that
query. See the launch-options API
and the attribution flow.
Read the launch query once at app start and pass it to your server. Keep the
Kuaishou value opaque. The source defines callback as the attribution value
for conversion reporting and says it is under 1,000 bytes. This flow applies
to commercial mini-game advertising, not ordinary websites. See the
documented query fields.
Rule setup and event mapping
The source documents three callback event values. It documents no purchase, subscription, or refund value. Map only these documented events. See the event enumeration.
| Product or hub event | Kuaishou request | When to send |
|---|---|---|
app_activation |
event_type=1 |
First app open |
signup |
event_type=2 |
First registration |
key_action |
event_type=143 |
IAA game or IAA tool key behavior |
purchase, refund, or other hub event |
Do not dispatch | No documented value |
Kuaishou defines activation as the first app open and registration as the first
registration. It limits event_type=143 to key behaviors for IAA games, IAA
tools, and similar ad-monetization products. The guide also names
key_action_category and key_action_threshold for describing that key
behavior. See the event enumeration.
Keep unsupported payment events in the hub and payment ledger. Return skipped
for the Kuaishou dispatch. See the hub event taxonomy.
Server-side conversion callback
Kuaishou documents a narrow conversion callback for the mini-game advertising flow. It is an HTTPS GET handled by Kuaishou's ad server. The documented endpoint and parameter names are:
GET https://ad.partner.gifshow.com/track/activate
event_type=<documented integer>
event_time=<13-digit millisecond timestamp>
callback=<original callback from the launch query>
The callback source says that callback comes from the client query,
event_type is an integer enumeration, and event_time is a 13-digit
millisecond timestamp. It says that {"result":1,...} means the report
succeeded. See Kuaishou's conversion-reporting instructions.
Use the callback as an opaque value. URL-encode every query value. This example uses only the parameter names and endpoint documented by Kuaishou:
curl --get 'https://ad.partner.gifshow.com/track/activate' \
--data-urlencode 'event_type=1' \
--data-urlencode 'event_time=<13-digit-ms>' \
--data-urlencode 'callback=<callback-from-launch-query>'
The source permits a server or client request. Prefer the server path so the
hub can record consent, event identity, and the response. The documented
callback example shows no bearer token or Authorization header. Do not add
one without a separate Kuaishou contract. See the callback definition.
This is not a universal web or CRM Conversions API. The fetched source gives no documented email, phone, order value, currency, browser event, or arbitrary event-name field for this callback. Do not invent a JSON body or add fields from another ad platform. See the documented callback fields.
Identity and consent
The callback documentation defines only callback, event_type, and
event_time among the fields used here. It defines no email, phone, IP,
user-agent, external-ID, or SHA-256 field. Do not send those identifiers. See
the callback parameter table.
The launch guide identifies account_id, campaign_id, unit_id, and
creative_id as advertising identifiers. Store them only for attribution
diagnostics. They do not replace consent. See the launch query fields.
Apply the hub consent gate before reading, storing, or dispatching ad-user data. Kuaishou's mini-program rules require clear notice and user consent when collecting user information. See the hub consent gate and Kuaishou's privacy rules.
Do not hash email or phone for this adapter. The source documents no hashing rule or field for such a hash. See the callback fields.
Click ID and first-party storage
For the documented mini-game path, the Kuaishou attribution value is the query
parameter callback. The guide also names account_id, campaign_id,
unit_id, and creative_id. These values arrive only through commercial
advertising. See the official attribution flow.
Capture the complete callback from ks.getLaunchOptionsSync().query when it
exists. Store it with the canonical event. The source defines no lifetime,
cookie name, web query parameter, or cross-device join rule. See the launch
API
and the hub click-ID rules.
Do not invent kuaishou_click_id, ksclid, ksuid, a cookie name, or a
seven-day or thirty-day attribution window. No such value or lifetime appears
in the fetched first-party sources. See the attribution flow.
Do not block first-party measurement when callback is absent. Return hub
skipped; the guide says only commercial advertising includes this value. See
the callback note.
Deduplication
The fetched Kuaishou callback documentation does not define an event ID,
idempotency key, deduplication field, or retry token. Do not send the hub
event_id as a guessed query parameter. Keep it in the hub dispatch record.
See the documented callback parameter table
and the hub deduplication policy.
Send activation and registration only once per product-defined user action, because the official event definitions say that activation and registration are first-time events, and the callback documents no idempotency key. Retry only a failure known to occur before the request reached Kuaishou, such as a connection error. For a timeout or other ambiguous failure after the request was sent, dead-letter it for manual reconciliation instead of replaying it; Kuaishou gives no dedup rule to make an automatic replay of an uncertain first-time event safe. See the event definitions and the hub retry policy.
DSP and API settings that override code
The guide names the 小程序推广 objective, 快手小程序/小游戏 scene, mini-game app ID, and monitoring configuration for activation objectives. It requires the campaign, ad group, and creative to be enabled and reviewed before using the creative-level 体验 test. See the DSP setup guide.
Reporting API
Kuaishou documents a mini-program advertising-data query API. It returns daily impressions, clicks, click rate, eCPM, and revenue. It is a reporting API, not a conversion endpoint. See the advertising-data API.
The documented operation is:
POST https://open.kuaishou.com/openapi/mp/developer/ad/data/query
The source places access_token and app_id in the query string. It defines
startTime, endTime, type, page, and pageSize in the JSON body. It
defines result=1 as a successful response. See the request definition.
This is a mini-program open-platform endpoint (open.kuaishou.com), a
different host and API family from the MAPI advertiser OAuth documented under
Account and access. The fetched source does not confirm
whether its access_token and app_id are the same KUAISHOU_AD_ACCESS_TOKEN
and KUAISHOU_AD_APP_ID obtained from the MAPI flow, or the separate
mini-program credential referenced by KUAISHOU_MINIAPP_ID. Do not assume the
MAPI advertiser token works here. Confirm the correct credential pair with
Kuaishou or the current mini-program open-platform authentication guide before
wiring this call.
Use the source's exact field casing for access_token, app_id, startTime,
endTime, type, page, pageSize, and result. See the report parameter
table.
The mini-game guide separately documents this real-time ECPM report endpoint:
POST https://ad.e.kuaishou.com/rest/openapi/gw/dsp/v1/report/ecpm_report
The guide says this flow uses an authorized advertiser ID and accepts open_id
or union_id, up to 200 IDs per request. Do not use these identifiers for a
website or CRM conversion flow. See the ECPM instructions.
Verification
Use three proofs. The source defines result=1 as a successful report and
directs testers to the DSP activation or key-action counts. See the callback
and test instructions.
- Request proof: record the redacted callback URL, selected
event_type, event time, and JSON result.result=1proves report acceptance. - Platform proof: check activation or key-action counts in the DSP report
view. For mini-program ad data, call the report API and confirm
result=1. - Business proof: reconcile registrations, payments, and refunds with first-party product or payment records. The callback documents no purchase or refund event.
See the official test flow. A result=1 response is request proof, not campaign attribution or purchase proof. Use hub verification.
Common pitfalls and security
The documented callback fields and hub rules imply these restrictions. See the callback field list and hub security.
- Do not call the mini-game callback a general CAPI or use the ad-data query as a conversion endpoint.
- Do not invent a website pixel, browser SDK, campaign endpoint, JSON body, hash field, or event parameter.
- Send the complete launch-query
callback; do not use a sample or truncation. - Keep
app_secret,access_token, andrefresh_tokenout of client code, logs, screenshots, and commits. Thecallbackvalue is read from the client launch query by design; forward it to the server without logging, screenshotting, or committing it. - Do not make payment success depend on Kuaishou callback success. Return a platform-specific failed or skipped status through the hub.
The Kuaishou mini-program rules require notice and user consent before collecting user information, and they require privacy handling for stored user information. Apply those requirements with the hub consent record. See the Kuaishou privacy rules and hub security.