Ocean Engine data integration plan
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
This document describes how to send Ocean Engine data back to Agentic Engine (hereinafter the AE system). This solution supports:
- Getting aggregated metric data from the all-in-one data report, including basic report metrics such as spend, clicks, and impressions, grouped by the ad account, ad group, campaign, and material dimensions
- Getting aggregated metric data from ad creative data, including basic report metrics such as spend, clicks, and impressions, grouped by the ad account, ad group, campaign, and material dimensions
- Getting aggregated metric data from the upgraded ad data report, that is, the data report of the new version of Ocean Engine Ads. It includes basic report metrics such as spend, clicks, and impressions, grouped by the ad account, ad group, campaign, and material dimensions
This document mainly describes how to connect data to the AE system through the underlying API. To learn how to configure the integration in the product backend, see this product documentation.
Before you start connecting Ocean Engine 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
The Ocean Engine data integration process is as follows:
- Log in to the Ocean Engine Open Platform, create a developer account and an app, and send the app's APP_ID and Secret and the login user ID to ThinkingAI staff
- In the callback URL field on the app management page, enter the URL provided by ThinkingAI staff
- Open the authorization link, log in to the Ocean Engine account that owns the ad accounts you want to pull data from, and complete authorization
- 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 Create a developer account and an app
Before connecting Ocean Engine data, you need to apply for an Ocean Engine developer account and create an app
- First, log in to or register an Ocean Engine account. Click this link to open the login and registration page. If you already have an Ocean Engine account, choose to log in at the lower-left corner and log in to that account. If you don't have an account, register an Ocean Engine account with your email address or mobile number
- After logging in, you are redirected to the Ocean Engine Open Platform. Click the Developer Management Console button in the upper-right corner of the page to open the developer console
-
If you haven't created a developer account, you need to enter developer information and pass the qualification review at this point. Because one company can register and verify only one developer account, make sure to apply with your company email address and keep the account safe. For the detailed application process, see the official documentation.
- For the developer type, select either advertiser or agency based on your situation. The differences between the two are as follows:
- Advertiser: can only apply for authorization of Zongheng organization accounts that belong to the same company entity as the developer account
- Agency: can only apply for authorization of agency accounts that belong to the same company entity as the developer account
- After the developer account is verified, go to the developer website, open the APPID Management page, and choose to create an app of the Ad Management type
- Note that when you create the app, you need to select the Data Reports permission in the permission scope
- After you submit the application, Ocean Engine reviews your app creation (APPID) application within one business day
2.2 Get the App ID and App Secret
After the app application is complete, go to the developer console, find App Management > Basic Apps in the left sidebar, select the app you created, and click Edit to open the Basic Information page. Find the APP_ID and Secret and send them to ThinkingAI staff.
2.3 Get the login user ID and complete authorization
Next, go to the Ocean Engine Open Platform, click the hexagon icon in the upper-right corner, click Ocean Engine Zongheng to enter the backend, click Account Information and Security in the upper-right corner, find the login user ID, and provide it to ThinkingAI staff.
After you provide the login user ID, ThinkingAI staff will provide you with a callback URL. Enter this URL in the Callback URL field on the app editing page.
After you fill it in, you can see the authorization URL at the bottom of the page. Copy it into a browser and open it.
The authorization page appears. Select All accounts of the current user, and make sure that Current login user owns the ad accounts you want to pull data from. Check that the login user ID in the red box is the login user ID you provided to ThinkingAI staff earlier. After confirming, click Agree to authorize to complete authorization.
3. Data pull
Ocean Engine provides a series of ad data reports. AE currently supports pulling the all-in-one data report, ad creative data, and the upgraded ad data report.
3.1 All-in-one data report
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| All-in-one data report API | Pull | Yes | Aggregated data | Yes | Yes | Yes | Yes |
The all-in-one data report supports pulling data at each ad granularity and at the material and keyword levels, so it has the richest analysis dimensions, but it supports fewer metrics than the standard data reports. Overall, it is the most commonly used data report.
3.1.1 Analysis dimensions
The following tables list the analysis dimensions supported by the all-in-one data report. The default grouping conditions are:
- STAT_GROUP_BY_TIME_HOUR
- STAT_GROUP_BY_CREATIVE_ID
To make changes, first check the grouping combination rules, and record what you need to change in the data integration configuration template:
| Field name | Description | Grouping condition | Default |
|---|---|---|---|
| stat_datetime | Time | STAT_GROUP_BY_TIME_MONTH STAT_GROUP_BY_TIME_WEEK STAT_GROUP_BY_TIME_DAY STAT_GROUP_BY_TIME_HOUR | Yes |
advertiser_id | Advertiser ID | STAT_GROUP_BY_ADVERTISER_ID STAT_GROUP_BY_CAMPAIGN_ID STAT_GROUP_BY_AD_ID STAT_GROUP_BY_CREATIVE_ID | Yes |
| campaign_name | Ad group name | STAT_GROUP_BY_CAMPAIGN_ID STAT_GROUP_BY_AD_ID STAT_GROUP_BY_CREATIVE_ID | Yes |
| campaign_id | Ad group ID | Yes | |
| ad_name | Campaign name | STAT_GROUP_BY_AD_ID STAT_GROUP_BY_CREATIVE_ID | Yes |
| ad_id | Campaign ID | Yes | |
| creative_id | Creative ID | STAT_GROUP_BY_CREATIVE_ID | Yes |
| bidword | Keyword name | STAT_GROUP_BY_BIDWORD_ID | |
| bidword_id | Keyword ID | ||
| query | Search term | STAT_GROUP_BY_QUERY | |
| pricing | Bidding method | STAT_GROUP_BY_PRICING | |
| image_mode | Creative type | STAT_GROUP_BY_IMAGE_MODE | |
| inventory | Preferred ad placement | STAT_GROUP_BY_INVENTORY | |
| campaign_type | Ad group type | STAT_GROUP_BY_CAMPAIGN_TYPE | |
| creative_material_mode | Creative type | STAT_GROUP_BY_CREATIVE_MATERIAL_MODE | |
| external_action | Conversion type | STAT_GROUP_BY_EXTERNAL_ACTION | |
| landing_type | Promotion type | STAT_GROUP_BY_LANDING_TYPE | |
| pricing_category | Ad type | STAT_GROUP_BY_PRICING_CATEGORY | |
| province_name | Province | STAT_GROUP_BY_PROVINCE_NAME | |
| city_name | City | Includes both STAT_GROUP_BY_CITY_NAME and STAT_GROUP_BY_PROVINCE_NAME | |
| gender | Gender | STAT_GROUP_BY_GENDER | |
| age | Age | STAT_GROUP_BY_AGE | |
| platform | Platform | STAT_GROUP_BY_PLATFORM | |
| ac | Network Type | STAT_GROUP_BY_AC | |
| material_id | Material ID | STAT_GROUP_BY_MATERIAL_ID | |
| playable_id | Playable material ID | STAT_GROUP_BY_PLAYABLE_ID | |
| playable_name | Playable material name | ||
| playable_url | Playable material link | ||
| playable_orientation | Playable material display orientation | ||
| playable_preview_url | Playable material preview link |
3.1.2 Included metrics
The following table shows some commonly used metrics supported by the all-in-one data report. There are too many metrics in total to show them all here. If needed, see the official documentation for descriptions of all metrics:
| Metric name | Display name | Default |
|---|---|---|
| active | Activations | Yes |
| active_cost | Activation cost | Yes |
| active_pay_cost | First payment cost | Yes |
| active_pay_rate | First payment rate | Yes |
| active_rate | Activation rate | Yes |
| active_register_cost | Registration cost | Yes |
| active_register_rate | Registration rate | Yes |
| attribution_active_pay_7d_per_count | 7-day average purchases per user | Yes |
| attribution_convert | Conversions (billing time) | Yes |
| attribution_convert_cost | Conversion cost (billing time) | Yes |
| attribution_deep_convert | Deep conversions (billing time) | Yes |
| attribution_deep_convert_cost | Deep conversion cost (billing time) | Yes |
| attribution_game_pay_7d_cost | 7-day payment cost | |
| attribution_game_pay_7d_count | 7-day purchases | |
| attribution_next_day_open_cnt | Next-day retained users | |
| attribution_next_day_open_cost | Next-day retention cost | |
| attribution_next_day_open_rate | Next-day retention rate | |
| avg_click_cost | Average cost per click | Yes |
| avg_show_cost | Average cost per 1,000 impressions | Yes |
| click | Clicks | Yes |
| click_install | Click installs | Yes |
| convert | Conversions | Yes |
| convert_cost | Conversion cost | Yes |
| convert_rate | Conversion data - Conversion rate | Yes |
| cost | Total spend | Yes |
| ctr | Click-through rate | Yes |
| deep_convert | Deep conversions | Yes |
| deep_convert_cost | Deep conversion cost | Yes |
| deep_convert_rate | Deep conversion rate | Yes |
| download | Download starts | Yes |
| game_addiction | Key actions | Yes |
| game_addiction_cost | Key action cost | Yes |
| game_addiction_rate | Key action rate | Yes |
| game_pay_cost | Payment cost | Yes |
| game_pay_count | Purchases | Yes |
| next_day_open | Next-day retention postbacks (not matched) | |
| next_day_open_cost | Next-day retention cost (not matched) | |
| next_day_open_rate | Next-day retention rate (not matched) | |
| pay_count | First purchases | Yes |
| play_100_feed_break | Plays to 99% progress | |
| play_25_feed_break | Plays to 25% progress | |
| play_50_feed_break | Plays to 50% progress | |
| play_75_feed_break | Plays to 75% progress | |
| play_duration_sum | Play duration, in ms | |
| total_play | Plays | |
| valid_play | Valid plays | |
| valid_play_cost | Valid play cost | |
| valid_play_rate | Valid play rate | |
| play_over_rate | Play completion rate | |
| redirect | Page redirects | |
| register | Registrations | |
| share | Shares | |
| show | Number of impressions | Yes |
| wifi_play | Wi-Fi plays | |
| wifi_play_rate | Wi-Fi play ratio |
3.1.3 API parameters
-
Ad account:
- Specify the ad accounts to pull data from
-
Time:
-
Data is pulled by day
- For search term reports, only data from the last 30 days is available
- For keyword reports, only data after 2019-05-19 is available
- For all reports, the time span can't exceed 30 days
-
Data can be aggregated by day or by hour. The default is by hour
-
3.1.4 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- Because the data returned by the all-in-one report 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_datetime field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
- The event name is oceanengine_show_click_convert_data
- All other fields are stored
3.2 Ad creative data
Ad creative data is the standard data report with the finest ad data granularity. Compared with the all-in-one data report, it has fewer analysis dimensions but supports more metrics.
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Ad creative data | Pull | No | Aggregated data | Yes | Yes | Yes | Yes |
3.2.1 Analysis dimensions
The following table lists the analysis dimensions supported by the ad creative data report. The default grouping conditions are:
- STAT_GROUP_BY_FIELD_STAT_TIME
- STAT_GROUP_BY_FIELD_ID
In addition, you can add at most one other grouping condition (such as STAT_GROUP_BY_INVENTORY in the table below), or add none and use the default grouping conditions
To make changes, record what you need to change in the data integration configuration template:
| Field name | Description | Grouping condition | Default |
|---|---|---|---|
| stat_datetime | Data start time, in the format:
| STAT_GROUP_BY_FIELD_STAT_TIME | Yes |
| advertiser_id | Advertiser ID | STAT_GROUP_BY_FIELD_ID | Yes |
| campaign_name | Ad group name | Yes | |
| campaign_id | Ad group ID | Yes | |
| ad_name | Campaign name | Yes | |
| ad_id | Campaign ID | Yes | |
| creative_id | Creative ID | Yes | |
| inventory | Ad placement | STAT_GROUP_BY_INVENTORY | |
| creative_material_mode | Creative type. Values:
| STAT_GROUP_BY_CREATIVE_MATERIAL_MODE | |
| landing_type | Promotion objective type | STAT_GROUP_BY_LANDING_TYPE | |
| pricing | Bid type | STAT_GROUP_BY_PRICING | |
| image_mode | Creative type | STAT_GROUP_BY_IMAGE_MODE | |
| province_name | Province | STAT_GROUP_BY_PROVINCE_NAME | |
| city_name | City | STAT_GROUP_BY_CITY_NAME | |
| gender | Gender | STAT_GROUP_BY_GENDER | |
| age | Age | STAT_GROUP_BY_AGE | |
| platform | Platform | STAT_GROUP_BY_PLATFORM | |
| ac | Type | STAT_GROUP_BY_AC |
3.2.2 Included metrics
The following table shows some commonly used metrics supported by the ad creative data report. There are too many metrics in total to show them all here. If needed, see the official documentation for descriptions of all metrics:
| Metric name | Display name | Default |
|---|---|---|
| active | Activations | Yes |
| active_cost | Activation cost | Yes |
| active_pay_cost | First payment cost | Yes |
| active_pay_rate | First payment rate | Yes |
| active_rate | Activation rate | Yes |
| active_register_cost | Registration cost | Yes |
| active_register_rate | Registration rate | Yes |
| attribution_active_pay_7d_per_count | 7-day average purchases per user | Yes |
| attribution_convert | Conversions (billing time) | Yes |
| attribution_convert_cost | Conversion cost (billing time) | Yes |
| attribution_deep_convert | Deep conversions (billing time) | Yes |
| attribution_deep_convert_cost | Deep conversion cost (billing time) | Yes |
| attribution_game_pay_7d_cost | 7-day payment cost | |
| attribution_game_pay_7d_count | 7-day purchases | |
| attribution_next_day_open_cnt | Next-day retained users | |
| attribution_next_day_open_cost | Next-day retention cost | |
| attribution_next_day_open_rate | Next-day retention rate | |
| avg_click_cost | Average cost per click | Yes |
| avg_show_cost | Average cost per 1,000 impressions | Yes |
| click | Clicks | Yes |
| click_install | Click installs | Yes |
| convert | Conversions | Yes |
| convert_cost | Conversion cost | Yes |
| convert_rate | Conversion data - Conversion rate | Yes |
| cost | Total spend | Yes |
| ctr | Click-through rate | Yes |
| deep_convert | Deep conversions | Yes |
| deep_convert_cost | Deep conversion cost | Yes |
| deep_convert_rate | Deep conversion rate | Yes |
| download | Download starts | Yes |
| game_addiction | Key actions | Yes |
| game_addiction_cost | Key action cost | Yes |
| game_addiction_rate | Key action rate | Yes |
| game_pay_cost | Payment cost | Yes |
| game_pay_count | Purchases | Yes |
| next_day_open | Next-day retention postbacks (not matched) | |
| next_day_open_cost | Next-day retention cost (not matched) | |
| next_day_open_rate | Next-day retention rate (not matched) | |
| pay_count | First purchases | Yes |
| play_100_feed_break | Plays to 99% progress | |
| play_25_feed_break | Plays to 25% progress | |
| play_50_feed_break | Plays to 50% progress | |
| play_75_feed_break | Plays to 75% progress | |
| play_duration_sum | Play duration, in ms | |
| total_play | Plays | |
| valid_play | Valid plays | |
| valid_play_cost | Valid play cost | |
| valid_play_rate | Valid play rate | |
| play_over_rate | Play completion rate | |
| redirect | Page redirects | |
| register | Registrations | |
| share | Shares | |
| show | Number of impressions | Yes |
| wifi_play | Wi-Fi plays | |
| wifi_play_rate | Wi-Fi play ratio |
3.2.3 API parameters
- Ad account:
- Specify the ad accounts to pull data from
- Time:
- Data is pulled by day
- The time span can't exceed 30 days
- Data is pulled by day
3.2.4 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- Because the data returned by the ad creative report 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_datetime field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
- The event name is oceanengine_creative_data
- All other fields are stored
3.3 Upgraded ad data report
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Upgraded ad data report | Pull | No | Aggregated data | Yes | Yes | Yes | Yes |
The upgraded ad data report is a new ad data report from Ocean Engine. You can use it to pull delivery data for the upgraded version of Ocean Engine Ads.
3.3.1 Analysis dimensions
The following are the dimensions supported by the upgraded ad data report. You can choose a Day level or Hour level report. Note that hourly reports are mutually exclusive with some dimensions
| Dimension | Field name | Day-level default | Hour-level default | Standardized field | Remarks |
|---|---|---|---|---|---|
| Ad account ID | - | Yes | Yes | ad_account_id | |
Time | stat_time_day (day level) stat_time_hour (hour level) | Yes | Yes | The following dimensions are not available for hourly reports
| |
| Project ID | cdp_project_id | Yes | Yes | ad_group_id | |
| Project name | cdp_project_name | Yes | Yes | ad_group_name | |
| Ad ID | cdp_promotion_id | Yes | Yes | ad_id | |
| Ad name | cdp_promotion_name | Yes | Yes | ad_name | |
| Package name | package_name | Yes | Yes | app_name | |
| Platform | platform | Yes | platform | Mutually exclusive with the following dimensions
Not available for hourly reports | |
| Gender | gender | ||||
| Age | age | ||||
| Network | ac | ||||
| Province | province_name | Mutually exclusive with the following dimensions
Not available for hourly reports | |||
| City | city_name | ||||
| Creative type | image_mode | ||||
| Promotion objective | landing_type | ||||
| Conversion goal | external_action | ||||
| Billing type | pricing | ||||
| Deep conversion goal | deep_external_action | ||||
| Download method | ad_platform_cdp_project_download_type | ||||
| Download link | ad_platform_cdp_project_download_url | ||||
| Conversion tracking URL | ad_platform_cdp_project_action_track_url | ||||
| Delivery mode | delivery_mode | ||||
| Ad bid | ad_platform_cdp_promotion_bid | ||||
| Deep conversion bid | ad_platform_cdp_promotion_deep_cpa_bid | ||||
| ROI coefficient | ad_platform_cdp_promotion_roi_goal | ||||
| Preferred placement | app_code |
3.3.2 Included metrics
The following table shows some commonly used metrics supported by the upgraded ad data report. There are too many metrics in total to show them all here
| Metric | Metric name | Description | Default | Standardized field | Remarks |
|---|---|---|---|---|---|
| Spend | stat_cost | The estimated amount spent on the ad during the delivery period. Same-day data may fluctuate and stabilizes the next day | Yes | cost | |
| Number of impressions | show_cnt | Number of times the ad is shown to users. Calculation: the number of impressions that the platform determines to be valid and bills for. | Yes | impressions | |
| Average cost per 1,000 impressions | cpm_platform | Average cost per 1,000 ad impressions. Formula: total spend/impressions*1000. | Yes | ||
| Clicks | click_cnt | When a user clicks the ad material, a click event is triggered, and the event is counted as one valid ad click. | Yes | clicks | |
| Click-through rate | ctr | Percentage of impressions that resulted in a click. Calculation: clicks/impressions*100% | Yes | ||
| Average cost per click | cpc_platform | Cost the advertiser pays for each click. Formula: total spend/clicks. | Yes | ||
| Conversions | convert_cnt | Conversions counted by the time the conversion event occurred. When evaluating costs, we recommend that advertisers refer to Conversion data (billing time). For example, if your ad is shown and clicked at 8:00 in the morning and the user activates at 19:00 in the evening, Ocean Engine counts the activation at 19:00. | Yes | installs | |
| Average conversion cost | conversion_cost | Average cost the advertiser pays for each conversion. Calculation: total spend/conversions. Same-day data may fluctuate. | Yes | ||
| Conversion rate | conversion_rate | Percentage of clicks that resulted in a conversion. Calculation: conversions/clicks*100% | Yes | ||
| Deep conversions | deep_convert_cnt | Deep conversions are recorded at the time the conversion event occurred. When evaluating deep conversion costs, we recommend that advertisers refer to Deep conversions (billing time). For example, if your ad is shown and clicked at 8:00 in the morning and the user activates at 19:00 in the evening, Ocean Engine counts the activation at 19:00. | |||
| Deep conversion cost | deep_convert_cost | Average cost the advertiser pays for each deep conversion. Calculation: total spend/deep conversions. Same-day data may fluctuate and stabilizes after 8:00 the next morning. | |||
| Deep conversion rate | deep_convert_rate | Percentage of conversions that resulted in a deep conversion. Calculation: deep conversions/conversions*100% | |||
| Activations | active | If you integrated through the API, activations are the activations that you recognize and that were sent back successfully. If you integrated the SDK, activations are the number of times users open your app after downloading it. | Yes | ||
| Activation cost | active_cost | Calculation: total spend/activations. | Yes | ||
| Activation rate | active_rate | Calculation: activations/clicks*100% | Yes | ||
| Registrations | active_register | If you integrated through the API, registrations are the registrations that you recognize and that were sent back successfully. If you integrated the SDK, registrations are the number of times users register. For details, see SDK integration documentation | Yes | ||
| Registration cost | active_register_cost | Cost the advertiser pays for each registration. Formula: total spend/registrations. Same-day data may fluctuate and stabilizes after 8:00 the next morning. | Yes | ||
| Registration rate | active_register_rate | Ratio of registered users to activated users | Yes | ||
| Key actions | game_addiction | Number of users with key in-app actions | |||
| Key action cost | game_addiction_cost | Cost the advertiser pays for each user with key in-app actions. Formula: total spend/key actions. Same-day data may fluctuate and stabilizes after 8:00 the next morning. | |||
| Key action rate | game_addiction_rate | Ratio of users with key actions to activated users | |||
| Plays | total_play | Number of plays longer than 0s. On some cellular networks, users need to tap to start playback manually, so the number of plays is sometimes lower than the number of impressions. | Yes | ||
| Valid plays | valid_play | Number of plays of 10 seconds or longer for bidding ads. If the total video length is less than 10 seconds, completed plays are counted. For brand ads, the number of plays of 5 seconds or longer in some apps (Toutiao, Toutiao Lite, Douyin, Xigua, Douyin Huoshan, and Pipixia) and of 3 seconds or longer in other apps. If the total video length is less than 5 seconds/3 seconds, completed plays are counted. | Yes | ||
| Valid play cost | valid_play_cost | Formula: total spend/valid plays. Same-day data may fluctuate and stabilizes after 8:00 the next morning. | Yes | ||
| Valid play rate | valid_play_rate | Formula: valid plays/impressions. | Yes | ||
| Valid plays per 1,000 | valid_play_of_mille | Valid plays/1000. Valid plays are the number of plays of 10 seconds or longer for bidding ads; if the total video length is less than 10 seconds, completed plays are counted. For brand ads, they are the number of plays of 5s or longer in some apps (Toutiao, Toutiao Lite, Douyin, Xigua, Douyin Huoshan, and Pipixia) and of 3s or longer in other apps; if the total video length is less than 5s/3s, completed plays are counted. | Yes | ||
| Cost per 1,000 valid plays | valid_play_cost_of_mille | Total spend/valid plays per 1,000. Same-day data may fluctuate and stabilizes after 8:00 the next morning. | Yes | ||
| Plays to 25% progress | play_25_feed_break | Number of times users played 25% or more of the video length, including plays that skipped ahead to this point | Incompatible dimensions:
| ||
| Plays to 50% progress | play_50_feed_break | Number of times users played 50% or more of the video length, including plays that skipped ahead to this point | |||
| Plays to 75% progress | play_75_feed_break | Number of times users played 75% or more of the video length, including plays that skipped ahead to this point | |||
| Plays to 99% progress | play_99_feed_break | Number of times users played 99% or more of the video length, including plays that skipped ahead to this point | |||
| Average duration per play | average_play_time_per_play | Calculation: total actual video play duration/total plays (excluding skipped duration) | |||
| Completion rate | play_over_rate | Formula: completed plays/plays. | |||
| Wi-Fi play ratio | wifi_play_rate | Video plays on Wi-Fi/total video plays | |||
| 3-second card impressions | card_show | For video card ads, the number of card impressions when the video plays to 3 seconds. | |||
| 3-second plays | play_duration_3s | Number of ad plays of 3 seconds or longer. If the total video length is less than 3 seconds, completed plays are counted. |
3.3.3 API parameters
- Ad account:
- Specify the ad accounts to pull data from
- Time:
- You can choose a day-level or hour-level report
3.3.4 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- Because the data returned by the upgraded ad data report 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 dimensions_stat_time_hour or dimensions_stat_time_day field in the data, that is, the date of the data, is set as the #event_time of the aggregated data
- The event name is oceanengine_custom_data
- 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:
Interface: Ocean Engine ad data report
---------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
Ocean Engine app APP_ID: XXX
Ocean Engine app Secret: XXX
List of advertiser (ad account) IDs: XXX, XXX
Login user ID: XXXXXXXXX
---------
Data type to pull: [all-in-one/ad creative/upgraded data report]
Analysis dimensions: XXX, XXX (leave blank to use the default)
Fields to pull: XXX, XXX (leave blank to use the default)
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Pull granularity: day level (only the upgraded data report supports hour level)
Scheduled pull: pull the data of the previous N days at X:00 every day (or pull N days of data every hour)
5. Integration testing
On the Management > Events page or the SQL IDE page in the AE system backend, search for the event
- oceanengine_show_click_convert_data
or
- oceanengine_creative_data
or
- oceanengine_custom_data
and check whether the corresponding data has been ingested
6. FAQ
Can we pull data if the same game is delivered under different Ocean Engine entities?
Yes. One AE project can correspond to multiple Ocean Engine tokens, so delivery data from different Ocean Engine users can be aggregated into the same AE project. To pull data from all Ocean Engine entities, you need to authorize each Ocean Engine user and add multiple integration plans in the Ocean Engine third-party integration configuration on the AE platform.
When I create an app in the Ocean Engine backend and fill in the app application, what do I enter for Callback URL?
When you create the app, you can enter your company's domain name for Callback URL first. After the app is added, you can change the callback URL to the Ocean Engine callback URL of the AE cluster.
Can't find the login user ID in the Ocean Engine backend?
You can confirm the login user ID in the Ocean Engine backend in either of two ways.
- Method 1: Ocean Engine Open Platform - click the hexagon icon in the upper-right corner, click Ocean Engine Zongheng - click Account Information and Security in the upper-right corner, and find the login user ID.
- Method 2: In Ocean Engine Open Platform - Developer Management Console - App Management - Edit App, enter the AE system callback URL - select the Data Reports permission scope - click Authorization URL - select All accounts of the current user to get the login user ID.
How do I get the advertiser IDs/ad account IDs under different login users?
Ocean Engine Open Platform - click the hexagon icon in the upper-right corner, and click Ocean Engine Ads Platform to display the ad account IDs under the corresponding login user. (If there is no Account ID column, click Custom column to add Account ID)
Why is no data pulled back after I enter the advertiser_id?
You may have entered the ad account ID of the Zongheng organization. You need to enter the IDs of the ad accounts used for delivery under the Zongheng organization, which you can get as follows:
curl --location --request GET 'https://ad.oceanengine.com/open_api/2/majordomo/advertiser/select/?advertiser_id={ZONGHENG_ORG_AD_ACCOUNT_ID}' \
--header 'Access-Token:{ACCESS_TOKEN}' \
--header 'Content-Type:application/x-www-form-urlencoded' \
--data-urlencode 'advertiser_id={ZONGHENG_ORG_AD_ACCOUNT_ID}'
How do I get the list of advertiser IDs for different login users under the same Zongheng organization?
- View the Zongheng organization ID on the right side of the Ocean Engine Zongheng page;
- Use the Get asset accounts under a Zongheng organization API to get the list of advertiser IDs for different login users under the Zongheng organization