TopOn full report query API
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 |
|---|---|---|---|---|---|---|---|---|
| Full report query API | API | Aggregated metrics | ✅ | ✅ | ✅ |
The full report refers to the full report data in the TopOn data report query API. It provides aggregated ad monetization data, including impression, click, and revenue metrics.
Integration process
- Log in to the TopOn dashboard and get the Publisher Key and APP ID
- Log in to the AE backend, go to the Third-party Integration module, add a TopOn integration, create an integration plan, and run a one-time pull to sync data
- Check whether the AE system receives the data successfully, and build reports
1. Get information from the TopOn dashboard
Before pulling data, ask your TopOn contact to enable the data report query API permission. After it is enabled, you can view the Publisher Key on the account management page of the developer dashboard.
Next, go to the app page of the TopOn dashboard and get the app ID of the app whose data you want to connect
2. Plan configuration
After you get the Publisher Key and App ID, 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 TopOn full report query API. 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 during authorization in the pop-up
Where:
-
APP ID: the app ID you just obtained
-
Publisher Key: the Publisher Key you just obtained
-
Brand: TopOn has divided its business (see this article for details). Enter the specific business brand you use
- If you use Taku, whose official website is takuad.com, enter
taku(if you leave it empty, taku is also assumed) - If you use TopOn, whose official website is www.toponad.com, enter
topon
- If you use Taku, whose official website is takuad.com, enter
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull the TopOn full report query API on a schedule. You can choose to pull data for a period of time at a specific time every day or every hour. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Pull time zone
You can also set the time zone of the pulled data. The default is UTC+8
2.4 Event Data Configuration
After you turn on the Event Data Configuration switch, all data sent back is written to the event table. We recommend that you enable event data ingestion.
2.5 Configuration
In the Configuration module, you can control the detailed settings of data pulling, including 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 |
| source | metrics | Metrics in the data; list type. Different levels support different metrics, so fill this in carefully |
| group_by | Grouping dimensions in the data; list type. Different levels support different group_by values, so fill this in carefully |
- Grouping dimensions
The following table shows all grouping dimensions supported by the full report query API. Note: When you query data from the last 10 days, you can select up to 6 grouping dimensions; when you query data from more than 10 days ago, you can select up to 3 grouping dimensions. time_zone and currency do not count toward the number of grouping dimensions. To adjust, add the grouping dimensions to source.group_by:
| Group-by dimension | Ingested field name | Type | Default | Remarks |
|---|---|---|---|---|
| date | date | String | Yes | Date, in the format YYYYmmdd |
app | app_id | String | Yes | App ID in the developer dashboard |
| app_name | String | Yes | App name | |
| app_platform | String | Yes | OS platform of the app | |
| app_pkg_name | String | Yes | Package name of the app | |
| placement | placement_id | String | Yes | Ad placement ID in the developer dashboard |
| placement_name | String | Yes | Ad placement name | |
adsource | adsource_network | String | Yes | Name of the ad platform that the ad source belongs to |
| adsource_token_position_id | String | Yes | Position ID of the ad source | |
| adsource_token_orientation | String | Yes | Orientation of the ad source | |
| adsource_token_video_muted | String | Yes | Whether the ad is muted | |
| adsource_token_app_id | String | Yes | App ID of the ad source | |
| adsource_token_app_name | String | Yes | App name of the ad source | |
| adsource_id | String | Yes | Ad source ID | |
| adsource_name | String | Yes | Ad source name | |
| network_firm_id | network_firm_id | String | Yes | Ad platform ID |
| network_firm | String | Yes | Ad platform name | |
Always included | time_zone | String | Yes | Time zone. Enum values: UTC+8, UTC+0, UTC-8 |
| currency | String | Yes | Currency of the developer account. The revenue formed by this field and the revenue field must match the revenue in the developer dashboard reports | |
adformat | adformat | String | Ad format. Enum values: Rewarded Video, Interstitial, Banner, Native, Splash | |
| area | area | String | Country (region) code | |
network | network | String | Ad platform account ID | |
| network_name | String | Ad platform account name | ||
| scenario | scenario_id | String | Ad scenario ID | |
| scenario_name | String | Ad scenario name | ||
traffic_group | traffic_group_id | String | Traffic group ID | |
| traffic_group_name | String | Traffic segment name | ||
| traffic_group_segment_id | String | Numeric segment ID of the traffic group. Note: For the default segment, segment_id = 0 and is not returned | ||
| channel | channel | String | Channel Name | |
| sdk_version | sdk_version | String | SDK version | |
| app_version | app_version | String | App version |
- Metric fields
By default, we store all of the following fields. To adjust them, modify source.metrics:
| Field | Remarks |
|---|---|
| new_user_rate | Percentage of new users |
| deu | DEU |
| engaged_rate | Penetration rate |
| imp_dau | Impressions / DAU |
| imp_deu | Impressions / DEU |
| impression_rate | Impression rate |
| dau | Returned only depending on the group_by conditions |
| arpu | Returned only when dau is returned |
| request | Requests |
| fillrate | Fill rate |
| impression | Number of impressions |
| click | Clicks |
| ctr | Click-through rate |
| ecpm | eCPM calculated by TopOn from the actual revenue pulled from the ad platforms through the report API and the impressions counted by TopOn. Formula: (revenue / impressions counted by TopOn) *1000. Note: eCPM is provided with a 1-day delay |
| revenue | Revenue of the third-party ad platform, in the currency of the developer account |
| request_api | Requests of the third-party ad platform |
| fillrate_api | Fill rate of the third-party ad platform |
| impression_api | Impressions of the third-party ad platform |
| click_api | Clicks of the third-party ad platform |
| ctr_api | Click-through rate of the third-party ad platform |
| ecpm_api | eCPM API calculated by TopOn from the actual revenue pulled from the ad platforms through the report API and the impression API. Formula: (revenue / impression API) *1000. Note: eCPM API is provided with a 1-day delay |
| estimate_revenue | Estimated revenue, in US dollars |
estimate_revenue_ecpm | Estimated eCPM calculated from the estimated revenue and the impressions counted by TopOn. Formula: (estimated revenue / impressions counted by TopOn) *1000. Note: 1. Estimated eCPM is provided on the same day; 2. For regular ad sources, it is calculated based on the manually entered eCPM price, and for bidding ad sources, it is calculated based on the real-time bidding price |
| ready_request | Number of isReady calls |
| ready_rate | isReady success rate |
| cy_estimate_revenue | Estimated revenue returned in the currency of the developer account |
| cy_estimate_revenue_ecpm | Estimated eCPM returned in the currency of the developer account, calculated in the same way as estimate_revenue_ecpm |
2.6 Event ingestion rules
By default, we write the pulled data to the AE project as events:
- Because the full report query API returns aggregated data, we use a fixed value as its user identifier. You can think of all data as attached to a single virtual user
- The date 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 topon_fullreport
- All other fields are stored
2.7 Standardized fields
The AE system standardizes some fields in the TopOn full report query API
| Original field | Standardized field | Description |
|---|---|---|
| adsource_name | te_ads_object.ad_name | Ad name |
| adsource_id | te_ads_object.ad_id | Ad ID |
| placement_name | te_ads_object.placement | Ad placement |
| network_firm | te_ads_object.media_source | Monetization channel |
| app_pkg_name | te_ads_object.app_id | App ID |
| app_name | te_ads_object.app_name | App name |
| app_platform | te_ads_object.platform | Platform, such as Android or iOS |
| area | te_ads_object.country | Country or region code |
| currency | te_ads_object.currency | Currency of the cost or revenue |
| impression | te_ads_object.impressions | Impressions |
| click | te_ads_object.clicks | Clicks |
| revenue | te_ads_object.revenue | Monetization revenue |