Ocean Engine upgraded ad data report
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Upgraded ad data report | API | Aggregated data | ✅ | ✅ | ✅ | ✅ |
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.
Integration process
- Log in to the Ocean Engine Open Platform and create a developer account and an app
- Get the app's APP_ID and Secret, and the login user ID
- Log in to the AE backend, go to the Third-party Integration module, and add an integration plan for the Ocean Engine upgraded ad data report
- 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
- Check whether the AE system receives the data successfully, and build reports
1. Get the authorization information
1.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
- You can write the app name, app icon, and app description as needed. Describe the app's purpose as sending Ocean Engine ad campaign data back to your own platform
- For the callback URL, enter www.thinkingdata.cn. This is only a temporary URL, and you need to change it after the plan is configured
- For the requested permissions, select at least the Data Reports permission
-
After you submit the application, Ocean Engine reviews your app creation (APPID) application within one business day
1.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 write them down.
1.3 Get the login user ID
Next, get the ID of the login user. Go to the Ocean Engine Open Platform, click the nine-dot icon in the upper-right corner, and click Ocean Engine Ads to open the backend. Find the login user ID on the account overview page and write it down
1.4 Summary
You have now obtained all the authorization information you need. You should now have the following information:
- App ID
- App Secret
- Login user ID
2. Plan configuration
After you get all the authorization information, log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the configuration page of the Ocean Engine upgraded ad data report. Follow this section to create the plan:
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information and enter the information you obtained in the previous step in the pop-up:
Where:
- APP ID: the app's APP ID
- APP Secret: the app's APP Secret
- Login ID: the login user ID
- Account ID List: the IDs of the ad accounts you want to pull data from. If you leave it empty, data for all ad accounts under the authorized user is pulled
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull the Ocean Engine upgraded ad data report on a schedule. You can choose to pull data for a period of time at a specific time every day. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Receive Settings
You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.
2.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion. Customizable; string type. All received data uses this name as the event name. |
| source | metrics | Metrics in the data; list type; customizable |
| group_by | Grouping dimensions in the data; list type; customizable | |
time_granularity | Time aggregation granularity of the data, that is, whether the pulled data is aggregated by day or by hour Valid values: day, hour |
You can modify the configuration as needed
2.4.1 Analysis dimensions
The following are the dimensions supported by the upgraded ad data report. Note that hourly granularity is mutually exclusive with some dimensions. To add other analysis dimensions, add the field names to source.group_by
| Field name | Display name | Default | Remarks |
|---|---|---|---|
| advertiser_id (always included; no need to specify) | Ad account ID | Yes | |
| cdp_project_id | Project ID | Yes | |
| cdp_project_name | Project name | Yes | |
| cdp_promotion_id | Ad ID | Yes | |
| cdp_promotion_name | Ad name | Yes | |
| package_name | Package name | ||
| platform | Platform | Mutually exclusive with the following dimensions
Not available at hourly granularity | |
| gender | Gender | ||
| age | Age | ||
| ac | Network | ||
| province_name | Province | Mutually exclusive with the following dimensions
Not available at hourly granularity | |
| city_name | City | ||
| image_mode | Creative type | ||
| landing_type | Promotion objective | ||
| external_action | Conversion goal | ||
| pricing | Billing type | ||
| deep_external_action | Deep conversion goal | ||
| ad_platform_cdp_project_download_type | Download method | ||
| ad_platform_cdp_project_download_url | Download link | ||
| ad_platform_cdp_project_action_track_url | Conversion tracking URL | ||
| delivery_mode | Delivery mode | ||
| ad_platform_cdp_promotion_bid | Ad bid | ||
| ad_platform_cdp_promotion_deep_cpa_bid | Deep conversion bid | ||
| ad_platform_cdp_promotion_roi_goal | ROI coefficient | ||
| app_code | Preferred placement |
2.4.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. To add other metrics, add the metric names to source.metrics
| Metric name | Display name | Default | Remarks |
|---|---|---|---|
| stat_cost | Spend | Yes | |
| show_cnt | Number of impressions | Yes | |
| cpm_platform | Average cost per 1,000 impressions | Yes | |
| click_cnt | Clicks | Yes | |
| ctr | Click-through rate | Yes | |
| cpc_platform | Average cost per click | Yes | |
| convert_cnt | Conversions | Yes | |
| conversion_cost | Average conversion cost | Yes | |
| conversion_rate | Conversion rate | Yes | |
| deep_convert_cnt | Deep conversions | ||
| deep_convert_cost | Deep conversion cost | ||
| deep_convert_rate | Deep conversion rate | ||
| active | Activations | Yes | |
| active_cost | Activation cost | Yes | |
| active_rate | Activation rate | Yes | |
| active_register | Registrations | Yes | |
| active_register_cost | Registration cost | Yes | |
| active_register_rate | Registration rate | Yes | |
| game_addiction | Key actions | ||
| game_addiction_cost | Key action cost | ||
| game_addiction_rate | Key action rate | ||
| total_play | Plays | Yes | |
| valid_play | Valid plays | Yes | |
| valid_play_cost | Valid play cost | Yes | |
| valid_play_rate | Valid play rate | Yes | |
| valid_play_of_mille | Valid plays per 1,000 | Yes | |
| valid_play_cost_of_mille | Cost per 1,000 valid plays | Yes | |
| play_25_feed_break | Plays to 25% progress | Incompatible with the following analysis dimensions:
| |
| play_50_feed_break | Plays to 50% progress | ||
| play_75_feed_break | Plays to 75% progress | ||
| play_99_feed_break | Plays to 99% progress | ||
| average_play_time_per_play | Average duration per play | ||
| play_over_rate | Completion rate | ||
| wifi_play_rate | Wi-Fi play ratio | ||
| card_show | 3-second card impressions | ||
| play_duration_3s | 3-second plays |
2.4.3 Data ingestion rules
- 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
2.5 Complete authorization
After completing the configuration, click Save and authorize in the upper right corner to save the plan configuration. Next, you need to complete the final authorization:
First, in the Authorization Information page that pops up, copy the URL in the first step
Go back to the Ocean Engine developer console, open the basic information page of the app you created earlier, and enter the URL you just copied as the callback URL
Then go back to the AE interface and click Go to authorization. This opens the Ocean Engine authorization page
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 entered in the plan configuration. After confirming, click Agree to authorize to complete authorization.
After completing authorization, in Authorization Information, click I have completed the above two steps in the lower-left corner, and then click Complete Authorization in the lower-right corner to finish the configuration. You have now completed the integration of the Ocean Engine upgraded ad data report.
2.6 Standardized fields
The AE system standardizes some fields in the Ocean Engine upgraded ad data report:
| Field name | Standardized field | Description |
|---|---|---|
| advertiser_id | te_ads_object.ad_account_id | Advertiser ID |
| cdp_project_name | te_ads_object.ad_group_name | Campaign name |
| cdp_project_id | te_ads_object.ad_group_id | Campaign ID |
| cdp_promotion_name | te_ads_object.ad_name | Creative name |
| cdp_promotion_id | te_ads_object.ad_id | Creative ID |
| package_name | te_ads_object.app_name | App name |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| CNY (fixed value) | te_ads_object.currency | Currency of the cost or revenue |
| show_cnt | te_ads_object.impressions | Number of impressions |
| click_cnt | te_ads_object.clicks | Clicks |
| convert_cnt | te_ads_object.installs | Click installs |
| stat_cost | te_ads_object.cost | Total spend |