TopOn device-level 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 |
|---|---|---|---|---|---|---|---|---|
| Device-level data report | API | User level | ✅ | ✅ | ✅ |
The device-level data report gets data by user dimension, including users' total impressions, clicks, and revenue over a period of time. Therefore, the AE system pulls the data of each user for each day separately, that is, a user's ad impressions, clicks, and revenue for each day.
Before you start connecting TopOn data, make sure that you have read the AE system's user identification rules and understand how AE identifies a user through #distinct_id and #account_id
Integration process
- Integrate the TopOn client SDK and the AE SDK, and set the AE user identification IDs in the TopOn SDK
- 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, and create an integration plan
- Check whether the AE system receives the data successfully, and build reports
1. Client SDK configuration
The first step in integrating TopOn data is to connect the AE SDK with the TopOn SDK on the client and set the AE system's user identification IDs in the TopOn SDK
1.1 Option 1 (automatic integration)
-
If you integrate the Android or iOS SDK:
- If the SDK version is 2.8.0~2.8.1, you can use this option directly
- If the SDK version is 2.8.2 or later, you also need to install the third-party data plugin. For details, see Android SDK third-party data and iOS SDK third-party data
-
If you integrate Unity SDK 2.4.0 or later, or Unreal SDK 1.5.0 or later, you can use this option directly
Note that AE SDK initialization and the code that enables automatic integration must run before the TopOn SDK is initialized. Follow these steps:
1. Initialize the AE SDK.
2. Call `enableThirdPartySharing` to set the distinct ID automatically.
3. Initialize the TopOn SDK.
- Android
- iOS
- Unity
- Unreal
// 1. Initialize the Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. Call the enableThirdPartySharing API to set ta_distinct_id in TopOn events
TDAnalytics.enableThirdPartySharing(TDThirdPartyType.TOP_ON);
// 3. Initialize the TopOn SDK
// ...
// 1. Initialize the iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. Call the enableThirdPartySharing API to set ta_distinct_id in TopOn events
[TDAnalytics enableThirdPartySharing:TDThirdPartyTypeTopOn];
// 3. Initialize the TopOn SDK
// ...
// 1. Initialize the Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. Call enableThirdPartySharing to set ta_distinct_id in TopOn events
TDAnalytics.EnableThirdPartySharing(TDThirdPartyType.TOPON);
// 3. Initialize the TopOn SDK
// ...
// 1. Initialize the Unreal SDK
UTDAnalytics::Initialize();
// 2. Call enableThirdPartySharing to set ta_distinct_id in TopOn events
TArray<FString> EventTypeList;
EventTypeList.Emplace(TEXT("TAThirdPartyShareTypeTOPON"));
UTDAnalytics::EnableThirdPartySharing(EventTypeList, AppID);
// 3. Initialize the TopOn SDK
// ...
After you change the distinct ID, call enableThirdPartySharing() again to sync the data.
This option works by automatically calling the initCustomMap method of ATSDK internally and passing in ATCustomRuleKeys.USER_ID, with the distinct ID of the TA project as the value.
1.2 Option 2 (manual integration)
Use TopOn's app-wide custom rule settings to pass AE's distinct_id into user_id in custom_rule of the TopOn SDK. For the calling method and code examples, see this document.
Note that AE SDK initialization and the initCustomMap call must run before the TopOn SDK is initialized. Follow these steps:
1. Initialize the AE SDK.
2. Call `initCustomMap` to set the distinct ID.
3. Initialize the TopOn SDK.
The following are manual integration code samples for the SDK on each platform:
- Android
- iOS
- Unity
// 1. Initialize the Android SDK
TDConfig config = TDConfig.getInstance(this, APPID, TE_SERVER_URL);
TDAnalytics.init(config);
// 2. Get the AE distinct ID, which corresponds to #distinct_id in AE
String distinctId = TDAnalytics.getDistinctId();
// 3. Set the distinct ID in events collected by TopOn
Map<String, String> customMap = new HashMap<>();
customMap.put(ATCustomRuleKeys.USER_ID,distinctId);
ATSDK.initCustomMap(customMap);
// 4. Initialize the TopOn SDK
// ...
// 1. Initialize the iOS SDK
TDConfig *config = [[TDConfig alloc] init];
config.appid = appid;
config.serverUrl = url;
config.mode = TDModeDebug;
[TDAnalytics startAnalyticsWithConfig:config];
// 2. Get the AE distinct ID, which corresponds to #distinct_id in AE
NSString *distinctId = [TDAnalytics getDistinctId];
// 3. Set the distinct ID in events collected by TopOn
[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:distinctId}];
// 4. Initialize the TopOn SDK
// ...
// 1. Initialize the Unity SDK
TDConfig config = new TDConfig("APPID","SERVER");
TDAnalytics.Init(config);
// 2. Get the AE distinct ID, which corresponds to #distinct_id in AE
var distinctId = TDAnalytics.GetDistinctId();
// 3. Set the distinct ID in events collected by TopOn
ATSDKAPI.initCustomMap(new Dictionary<string, string> { { "user_id", distinctId } });
// 4. Initialize the TopOn SDK
// ...
2. Get information from the TopOn dashboard
After completing the SDK configuration, log in to the TopOn dashboard to get the authorization information required for pulling data.
To get the authorization information, first ask your TopOn contact to enable the device-level data report API permission. After it is enabled, you can get 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
3. Plan configuration
After you complete the SDK configuration and 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 device-level data report. Follow this section to create the plan:
3.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
3.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull the TopOn device-level data report 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
3.3 Pull time zone
You can also set the time zone of the pulled data. The default is UTC+8
3.4 User identification fields
Because the TopOn device-level data report contains user-level data, you need to set user identification rules for it, that is, the AE system's user identification IDs set in the TopOn SDK. Based on this configuration, the AE system sets these fields as the user identification fields of the data when it converts the callback data.
If you configured the client SDK as described in the previous step of this document, use the following configuration:
- Field associated with the account ID: none
- Field associated with the distinct ID: user_id
3.5 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.
3.6 User Properties Configuration
By default, the AE system does not write data from the TopOn device-level data report to user properties. If you want to write some fields to the user table, first turn on the rule so that it runs, and then use Property Mapping to add the fields to be written to the user table. For Source Property, enter the ingestion name of the field:
3.7 Configuration
In the Configuration module, you can control the detailed settings of data pulling, such as 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 |
| transfer | double_columns | Metric fields. Do not modify |
3.8 Event ingestion rules
- The AE system uses 00:00 of each day as the event's #event_time
- The default event name is -- ta_ad_revenue_topon
- All other fields are stored. The following are all the event properties that are stored
| Field | Remarks |
|---|---|
| placement_id | Ad placement ID |
| placement_name | Ad placement name |
| placement_format | Ad type: 0: native; 1: rewarded_video; 2: banner; 3: interstitial; 4: splash |
| android_id | Device ID, androidid |
| gaid | Google advertising device ID |
| idfa | iOS device ID |
| area | Country |
| impression | Number of impressions |
| click | Clicks |
| revenue | Revenue, split to the device level based on the revenue of the third-party ad platforms. The currency is the same as configured in the developer dashboard |
ecpm | eCPM calculated by TopOn from the revenue split by device impressions based on the revenue API and the device impressions counted by TopOn. Formula: (device revenue / device impressions counted by TopOn) * 1000. Note: eCPM is provided with a 2-day delay |
| is_abtest | Control group or test group: 0: control group, or A/B testing not enabled; 1: test group |
| traffic_group_id | Control group or test group ID |
| segment_id | Traffic segment ID |
| segment_name | Traffic segment name |
| idfv | iOS device ID |
| oaid | Android device ID |
| user_id | Developer's custom user ID |
| network_firm_id | Ad platform ID |
| network_firm | Ad platform name |
| currency | Currency of the developer account. USD means US dollars, and CNY means Chinese yuan |
| os_version | OS version of the iOS device |
| att_status | ATT authorization status of the iOS device: 0: Not determined (authorization not yet decided); 1: Restricted; 2: Denied; 3: Authorize (authorized) |
| imei | Android device identifier |
| device_type | iOS device type. Enum values: 0: non-iOS device; 1: iphone; 2: ipad |
| brand | Device brand name |
| model | Device model |
| app_vn | App version name |
| app_vc | App version code |
| new_user_type | New user type. Enum values: 1: new user; 2: not a new user |
| channel | Channel, passed in by the developer through the TopOn SDK |
| estimate_revenue | Estimated revenue. For bidding ad sources, the estimated revenue is the sum of real-time ad impression prices; for non-bidding ad sources, it is the manually entered eCPM price * the impressions counted by TopOn |
3.9 Standardized fields
The AE system standardizes some fields in the TopOn device-level data report
| Original field | Standardized field | Description |
|---|---|---|
| network_firm | te_ads_object.media_source | Monetization channel |
| placement_name | te_ads_object.placement | Ad placement |
| 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 |