manuallatestProduct Manual / Kuaishou Ads data integration solution
Kuaishou Ads data integration solution
Last updated: 2022-07-27
1. Integration plan overview
tip
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
This document describes how to send Kuaishou Magnetic Engine ad data back to Agentic Engine (hereinafter the AE system). This solution supports:
- Sending back aggregated metric data through the Kuaishou Marketing API, including impression, click, install, cost, and conversion metrics
Before you start connecting Kuaishou Ads data, make sure you have read the AE system data rules and understand AE's data structure. We also recommend that you give the information needed to pull data to our customer success manager, using the format in the data integration configuration template.
Process
-
Register a Kuaishou developer account and create an app
-
Provide ThinkingAI staff with the APP_ID of the Kuaishou app and the APP ID of the AE project to connect. ThinkingAI staff will provide a callback link. Set this link as the callback link of the Kuaishou app
-
Open the authorization URL provided by ThinkingAI staff and complete authorization
-
Determine how to pull data:
- Advertiser data
- Ad creative data (custom)
- Programmatic creative 2.0 data
- Traffic boost order data
-
Determine the data dimensions, metric types, pull frequency, and time range to pull
-
ThinkingAI staff complete the data pull development
-
Build dashboards and reports in the AE backend, and complete data validation
2. Preparation before integration
2.1 Register a Kuaishou developer account
Before you call the Kuaishou Marketing API, you need a Kuaishou developer account. We recommend that you follow the process in the Kuaishou official documentation to register a developer account.
2.2 Configure the callback URL and complete authorization
- After registering the Kuaishou developer account, fill in the app details in App Management to create the corresponding app
- The app details include the authorization callback link. Provide ThinkingAI staff with the app_id that Kuaishou returns after you apply for the app, and the APP ID of the AE project you want to connect. ThinkingAI staff will provide you with a callback link. Enter this URL in the corresponding field in Kuaishou App Management.
- After you complete the settings, ThinkingAI staff will provide you with an authorization link. After you click the authorization link, the following page appears. Note down the Kuaishou ID here and provide it to ThinkingAI staff. Then click User-based authorization, select Agree to the terms of use, and click Confirm authorization to complete authorization
3. Data pull
The Kuaishou Marketing API provides multiple data types. The data types currently supported by the AE system are:
- Advertiser data
- Ad creative data (custom)
- Programmatic creative 2.0 data
- Traffic boost order data
3.1 Advertiser data
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Advertiser data | Pull | No | Aggregated data | Yes | Yes | Yes | Yes |
3.1.1 API parameters
-
Advertiser account:
- Specify the IDs of the advertiser accounts to pull data from
-
Time:
- Data in units of full days or hours
- The time granularity of metrics can be day or hour
3.1.2 Included fields
Advertiser data metrics include metric data for multiple business types (such as online stores and livestream selling). This section only lists some commonly used metrics. For the complete metric list, see the Advertiser data documentation:
- Metric fields
| Metric | Description |
|---|---|
| charge | Spend (CNY) |
| show | Cover impressions |
| photo_click | Cover clicks |
| aclick | Material impressions |
| bclick | Actions |
| photo_click_ratio | Cover click-through rate |
| impression_1k_cost | Average cost per 1,000 impressions (CNY) |
| photo_click_cost | Average cost per click (CNY) |
| action_cost | Average cost per action (CNY) |
| share | Shares |
| comment | Comments |
| like | Likes |
| follow | New follows |
| cancel_follow | Unfollows |
| report | Reports |
| block | Blocks |
| negative | "Show fewer like this" count |
| download_started | App download data - Android download starts |
| download_completed | App download data - Android download completions |
| activation | App download data - Activations |
| event_pay_first_day | App download data - First-day purchases |
| event_pay_purchase_amount_first_day | App download data - First-day purchase amount |
| event_pay_first_day_roi | App download data - First-day ROI |
| event_pay | App download data - Purchases |
| event_pay_purchase_amount | App download data - Purchase amount |
| event_pay_roi | App download data - ROI |
| event_register | App download data - Registrations |
| event_register_cost | App download data - Registration cost |
| event_register_ratio | App download data - Registration rate |
| event_order_paid | App download data - Successful payments |
| event_order_paid_purchase_amount | App download data - Successful payment amount |
| event_order_paid_cost | App download data - Cost per payment |
| played_end | Completed plays |
| played_three_seconds | Valid plays |
| click_1k_cost | Average cost per 1,000 material impressions (CNY) |
| event_button_click | Button clicks |
| event_button_click_cost | Button click cost: same-day spend / button clicks |
| event_button_click_ratio | Button click-through rate: button clicks / actions |
| play_end_ratio | Completion rate: button clicks / actions |
| event_watch_app_ad | Ad views |
| event_ad_watch_times | Ad view count |
| event_ad_watch_times_ratio | Ad view count conversion rate |
| event_ad_watch_times_cost | Ad view count cost |
| ad_show | Ad impression |
| click_conversion_ratio | Click-to-activation rate |
| conversion_cost | Cost per activation |
| download_completed_cost | Cost per Android download completion (CNY) |
| download_completed_ratio | Android download completion rate |
| download_conversion_ratio | Download-completion-to-activation rate |
| download_started_cost | Cost per Android download start (CNY) |
| download_started_ratio | Android download start rate |
| conversion_num | Conversions (attributed by postback time) |
| conversion_num_cost | Conversion cost (attributed by postback time) |
| conversion_ratio | Conversion rate (attributed by postback time) |
- Dimension fields
| Dimension | Description |
|---|---|
| advertiser_id | Ad account ID |
| campaign_id | Campaign ID |
| campaign_name | Campaign name |
| unit_id | Ad group ID |
| unit_name | Ad group name |
| creative_id | Ad creative ID |
| creative_name | Ad creative name |
| status | 1 - Delivering; 2 - Paused; 3 - Deleted |
3.1.3 Ingestion rules
By default, we write the pulled data to the AE project as events:
- Because advertiser data is aggregated data, we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
- The stat_date and stat_hour fields in the data, that is, the concatenation of the date and the hour, are used as the data's #event_time
- The event name is kuaishou_ads_account_report
- All other fields are stored
3.2 Ad creative data (custom)
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Ad creative data (custom) | Pull | No | Aggregated data | Yes | Yes | Yes | Yes |
If you configured an ad whose Creative production method is Custom in the Magnetic Engine backend, you can use this API to get its data:
3.2.1 API parameters
-
Advertiser account:
- Specify the IDs of the advertiser accounts to pull data from
-
Time:
- Data in units of full days or hours
- The time granularity of metrics can be day or hour
3.2.2 Included fields
Ad creative data metrics include metric data for multiple business types (such as online stores and livestream selling). This section only lists some commonly used metrics. For the complete metric list, see the Ad creative data - custom documentation:
- Metric fields
| Metric | Description |
|---|---|
| charge | Spend (CNY) |
| show | Cover impressions |
| photo_click | Cover clicks |
| aclick | Material impressions |
| bclick | Actions |
| photo_click_ratio | Cover click-through rate |
| impression_1k_cost | Average cost per 1,000 impressions (CNY) |
| photo_click_cost | Average cost per click (CNY) |
| action_cost | Average cost per action (CNY) |
| share | Shares |
| comment | Comments |
| like | Likes |
| follow | New follows |
| cancel_follow | Unfollows |
| report | Reports |
| block | Blocks |
| negative | "Show fewer like this" count |
| download_started | App download data - Android download starts |
| download_completed | App download data - Android download completions |
| activation | App download data - Activations |
| event_pay_first_day | App download data - First-day purchases |
| event_pay_purchase_amount_first_day | App download data - First-day purchase amount |
| event_pay_first_day_roi | App download data - First-day ROI |
| event_pay | App download data - Purchases |
| event_pay_purchase_amount | App download data - Purchase amount |
| event_pay_roi | App download data - ROI |
| event_register | App download data - Registrations |
| event_register_cost | App download data - Registration cost |
| event_register_ratio | App download data - Registration rate |
| event_order_paid | App download data - Successful payments |
| event_order_paid_purchase_amount | App download data - Successful payment amount |
| event_order_paid_cost | App download data - Cost per payment |
| click_1k_cost | Average cost per 1,000 material impressions (CNY) |
| event_button_click | Button clicks |
| event_button_click_cost | Button click cost: same-day spend / button clicks |
| event_button_click_ratio | Button click-through rate: button clicks / actions |
| play_end_ratio | Completion rate: button clicks / actions |
| event_watch_app_ad | Ad views |
| event_ad_watch_times | Ad view count |
| event_ad_watch_times_ratio | Ad view count conversion rate |
| event_ad_watch_times_cost | Ad view count cost |
| ad_show | Ad impression |
| click_conversion_ratio | Click-to-activation rate |
| conversion_cost | Cost per activation |
| download_completed_cost | Cost per Android download completion (CNY) |
| download_completed_ratio | Android download completion rate |
| download_conversion_ratio | Download-completion-to-activation rate |
| download_started_cost | Cost per Android download start (CNY) |
| download_started_ratio | Android download start rate |
| conversion_num | Conversions (attributed by postback time) |
| conversion_num_cost | Conversion cost (attributed by postback time) |
| conversion_ratio | Conversion rate (attributed by postback time) |
- Dimension fields
| Dimension | Description |
|---|---|
| advertiser_id | Ad account ID |
| campaign_id | Campaign ID |
| campaign_name | Campaign name |
| unit_id | Ad group ID |
| unit_name | Ad group name |
| creative_id | Ad creative ID |
| creative_name | Ad creative name |
| status | 1 - Delivering; 2 - Paused; 3 - Deleted |
3.2.3 Ingestion rules
By default, we write the pulled data to the AE project as events:
- Because ad creative data is aggregated data, we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
- The stat_date and stat_hour fields in the data, that is, the concatenation of the date and the hour, are used as the data's #event_time
- The event name is kuaishou_ads_creative_report
- All other fields are stored
3.3 Programmatic creative 2.0 data
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Programmatic creative 2.0 data | Pull | No | Aggregated data | Yes | Yes | Yes | Yes |
If you configured ads whose Creative production method is Programmatic creative in the Magnetic Engine backend, you can use this API to get their data:
3.3.1 API parameters
-
Advertiser account:
- Specify the IDs of the advertiser accounts to pull data from
-
Time:
- Data for a time range accurate to the hour
- The time granularity of metrics can be day or hour
3.3.2 Included fields
Programmatic creative data metrics include metric data for multiple business types (such as online stores and livestream selling). This section only lists some commonly used metrics. For the complete metric list, see the Programmatic creative 2.0 data documentation:
- Metric fields
| Metric | Description |
|---|---|
| charge | Spend (CNY) |
| show | Cover impressions |
| photo_click | Cover clicks |
| aclick | Material impressions |
| bclick | Actions |
| photo_click_ratio | Cover click-through rate |
| impression_1k_cost | Average cost per 1,000 impressions (CNY) |
| photo_click_cost | Average cost per click (CNY) |
| action_cost | Average cost per action (CNY) |
| share | Shares |
| comment | Comments |
| like | Likes |
| follow | New follows |
| cancel_follow | Unfollows |
| report | Reports |
| block | Blocks |
| negative | "Show fewer like this" count |
| download_started | App download data - Android download starts |
| download_completed | App download data - Android download completions |
| activation | App download data - Activations |
| event_pay_first_day | App download data - First-day purchases |
| event_pay_purchase_amount_first_day | App download data - First-day purchase amount |
| event_pay_first_day_roi | App download data - First-day ROI |
| event_pay | App download data - Purchases |
| event_pay_purchase_amount | App download data - Purchase amount |
| event_pay_roi | App download data - ROI |
| event_register | App download data - Registrations |
| event_register_cost | App download data - Registration cost |
| event_register_ratio | App download data - Registration rate |
| event_order_paid | App download data - Successful payments |
| event_order_paid_purchase_amount | App download data - Successful payment amount |
| event_order_paid_cost | App download data - Cost per payment |
| played_end | Completed plays |
| played_three_seconds | Valid plays |
| click_1k_cost | Average cost per 1,000 material impressions (CNY) |
| event_button_click | Button clicks |
| event_button_click_cost | Button click cost: same-day spend / button clicks |
| event_button_click_ratio | Button click-through rate: button clicks / actions |
| play_end_ratio | Completion rate: button clicks / actions |
| event_watch_app_ad | Ad views |
| event_ad_watch_times | Ad view count |
| event_ad_watch_times_ratio | Ad view count conversion rate |
| event_ad_watch_times_cost | Ad view count cost |
| ad_show | Ad impression |
| click_conversion_ratio | Click-to-activation rate |
| conversion_cost | Cost per activation |
| download_completed_cost | Cost per Android download completion (CNY) |
| download_completed_ratio | Android download completion rate |
| download_conversion_ratio | Download-completion-to-activation rate |
| download_started_cost | Cost per Android download start (CNY) |
| download_started_ratio | Android download start rate |
| conversion_num | Conversions (attributed by postback time) |
| conversion_num_cost | Conversion cost (attributed by postback time) |
| conversion_ratio | Conversion rate (attributed by postback time) |
- Dimension fields
| Dimension | Description |
|---|---|
| campaign_id | Campaign ID |
| campaign_name | Campaign name |
| unit_id | Ad group ID |
| unit_name | Ad group name |
| creative_id | Creative ID |
| photo_url | Video URL |
| photo_id | Video ID |
| image_token | Cover ID |
| cover_url | Cover URL |
| description | Ad copy |
| pic_id | Image library image ID |
| pic_list | Kuaishou Union images (landscape/portrait) |
| pic_url_list | Kuaishou Union image URLs (landscape/portrait) |
3.3.3 Ingestion rules
By default, we write the pulled data to the AE project as events:
- Because programmatic creative 2.0 data is aggregated data, we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
- The stat_date and stat_hour fields in the data, that is, the concatenation of the date and the hour, are used as the data's #event_time
- The event name is kuaishou_ads_program_creative_report
- All other fields are stored
3.4 Traffic boost order data
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Traffic boost order data | Pull | No | Aggregated data | Yes | Yes | Yes | Yes |
Traffic boost data gets yesterday's spend for traffic boost orders created in the last 30 days
3.4.1 API parameters
- Advertiser account:
- Specify the IDs of the advertiser accounts to pull data from
3.4.2 Included fields
The metrics and analysis dimensions of traffic boost data are fixed. The following are all the fields:
- Metric fields
| Metric | Description |
|---|---|
| amount | Amount |
| consume_amount | Spend amount |
| view | Cover impressions |
| play | Plays |
| action | Actions |
| conversion | Activations |
| play_percent | Cover click-through rate |
| action_percent | Action rate |
| cpm | cpm |
| cpc_of_action | Average cost per action |
| cpa | Cost per activation |
- Dimension fields
| Dimension | Description |
|---|---|
| supplement_order_id | Boost order ID |
| task_id | Task ID |
| order_id | Juxing order ID |
| star_user_id | Creator ID |
| account_id | account_id |
| unit_ids | unit_id |
| star_name | Creator name |
| status | Status |
| promotion_begin_time | Promotion start time |
| promotion_end_time | Promotion end time |
| target_type | Target audience type |
| unit_type | Optimization goal/delivery goal |
| unit_price | Bid/target cost |
| supplement_order_sense_id | Ad placement |
| android_app_name | Android app name |
| package_name | Android app package name |
3.4.3 Ingestion rules
By default, we write the pulled data to the AE project as events:
- Because the post-delivery data of traffic boost orders is aggregated data, we use a fixed value as its user identifier. You can think of all the data as attached to one virtual user
- Yesterday's date (that is, 'YYYY-MM-DD 00:00:00') is used as the #event_time of the data
- The event name is kuaishou_ads_supplement_report
- All other fields are stored
4. Data integration configuration template
After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:
Data interface: Kuaishou Magnetic Engine Marketing API
---------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
---------
APP_ID and secret on the Magnetic Engine App Management page: XXX
App package name for filtering in the boost API: xxx
---------
Data type to pull: (advertiser/custom ad creative/programmatic creative 2.0/post-delivery data of traffic boost orders)
List of advertiser (ad account) IDs to pull data from: XXX, XXX
Fields to pull: XXX, XXX
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Scheduled pull: pull the previous day's data at X:00 every day
5. Data validation and usage
You can analyze the following events (datasets) in Events Analysis:
- kuaishou_ads_account_report
- kuaishou_ads_creative_report
- kuaishou_ads_program_creative_report
- kuaishou_ads_supplement_report
Was this page helpful?