# TopOn Integration Solution
This article will introduce how to integrate TopOn data into the TE platform. Currently, the TE backend supports integrating TopOn's Device Reporting API (opens new window).
TIP
Please note that data generated from integrating with third-party platforms will be included in the consumed data volume of the cluster.
# Summary
| Interface | Integration Type | Data Granularity | Attribution | Cost | Revenue | Impression | Click | Conversion |
|---|---|---|---|---|---|---|---|---|
| Device Reporting API | API | User Level | ✅ | ✅ | ✅ |
Device Reporting API (opens new window) can obtain aggregated metrics based on users, including users' total impressions, clicks, and revenue data over a period of time. Therefore, the TE system will separately pull data for each user every day, which includes the number of ad impressions, clicks, and revenue generated by the user for that day.
Before starting to integrate TopOn data, please ensure that you have read the TE system user identification rules and understand how TE identifies a user through #distinct_id and #account_id.
# Integration Process
- Integrate TopOn client SDK (opens new window) and TE SDK, and set TE's user identification ID in TopOn SDK.
- Log in to the TopOn backend and obtain Publisher Key and APP Key.
- Log in to the TE backend, enter the third-party integration module, add TopOn integration, create an integration plan, and execute a one-time synchronous data pull.
- Check whether the TE system has successfully received the data and complete the report construction.
# Client SDK Configuration
The first step to integrate TopOn data is to complete the integration between TE SDK and TopOn SDK on the client side, and set TE system's user identification ID in TopOn SDK.
# 1.1 Option 1 (automatic integration)
- If you are using TE SDK version 2.8.0~2.8.1, you can use this option directly.
- If you are using TE SDK version 2.8.2 and above, you also need to install a third-party data plugin. Please refer to the Android SDK integration document and iOS SDK integration document for details.
This option is an automatic integration option. Please call the following code after initializing the TE client SDK to enable it:
// Initialize TE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// Enable TopOn ID association
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);
// Initialize TopOn SDK
// ...
// After modifying the visitor ID, it is necessary to synchronize the data again (optional).
instance.identify("distinct_id");
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TOP_ON);
The principle of this solution is to automatically call the initCustomMap method of ATSDK, passing in ATCustomRuleKeys.USER_ID, and passing in the value of the TA project's visitor ID.
# 1.2 Option 2 (manual integration)
Through the TopOn App's global custom rule settings, the TA's distinct_id is passed into the user_id in TopOn SDK's custom_rule. The method of invocation and code example can refer to this document (opens new window).
Sample iOS client code configuration:
[[ATAPI sharedInstance] setCustomData:@{kATCustomDataUserIDKey:self.TA_DISTINCT_ID}];
Sample Android client code configuration:
Map<String, String> customMap = new HashMap<>();
customMap.put(ATCustomRuleKeys.USER_ID,"ta_distinct_id");
ATSDK.initCustomMap(customMap);
WARNING
To report through the setCustomData (iOS) method or the initCustomMap (Android) method, it needs to be completed before the initialization of TopOn SDK. Otherwise, some user_id may not be obtained.
# Obtain TopOn's Information
After configuring the SDK, you need to log in to the TopOn platform to get the authorization information required to pull data.
To obtain the authorization information, you need to apply to the TopOn contact person to open the device-level data reporting API permission. After the permission is successfully opened, you can view the Publisher Key and App Key on the account management page of the developer backend. Please copy these two pieces of information, which will be used in the TE system configuration later.
# TE Third-party Integration Page Configuration
After completing the SDK configuration and obtaining TopOn's authorization, the next step is to log in to the TE system backend and complete the configuration of TopOn in the "Third-party Integration" module. The following figure is the configuration interface of TopOn. Please turn on the "Connect Switch" to start the configuration of TopOn:
# 3.1 User ID Mapping
Since TopOn can only return a custom user ID field, it has not opened up the modification of identification fields. You need to complete the configuration of the client SDK according to this document. Therefore, in TopOn's data, the user_id is the visitor ID of the TE system.
# 3.2 Integration Plan
Next, you need to set the configuration for pulling data. There are mainly two configurations:
- Pull Time Zone: You can choose UTC-8, +8, or ±0 time zones.
- Data Sync Scheduling: Set the strategy for TE system to pull data regularly, and you can choose to pull data for a period of time every day or every hour. Please note that the TopOn Device Reporting API only supports pulling data for the past 29 days.
# 3.3 Create Integration Plan
In order to pull data, you also need to create an integration plan and fill in the authorization information obtained from TopOn backend. As shown in the figure below, set a plan name for it and fill in the Publisher Key and App Key.
# 3.4 Save Configuration and Single Pull
Finally, please check that all the above configurations are filled in correctly and click the "Save Configuration" button in the lower right corner of the page. At this point, you have completed all the configuration work of TopOn integration.
After saving the configuration, we recommend that you click the "Single Pull Task" button in the lower right corner of the page to manually trigger a data pull. In the data pull pop-up window, please set the scope of data to be pulled and which plans need to be pulled.
# Data Storage Logic
# 4.1 User Identification Rules
Due to the field limitations of TopOn API data, the user identification rules for TopOn API data are fixed as follows:
- Account ID: Not checked, leave it blank directly
- Distinct ID: Check if user_id exists. If yes, set it to #distinct_id. If not, the data will be considered invalid and discarded directly
# 4.2 Event Storage Rules
- TE system takes 0 o'clock every day as the #event_time of the event
- The event name is -- ta_ad_revenue_topon
- All other fields will be stored
# 4.3 Standardized Fields
The TopOn data contains the following event attributes, and TE system will standardize some of the fields:
| Original Field | Meaning | Standardized Field |
|---|---|---|
| placement_id | Placement ID | |
| placement_name | Placement name | te_ads_object.placement |
| placement_format | adformat 0: native,1: rewarded_video,2: banner,3: interstitial,4: splash | |
| android_id | androidid | |
| gaid | google advertising id | |
| idfa | ios device id | |
| area | country code | |
| impression | impression number | |
| click | click number | |
| revenue | revenue, split the device level according to the revenue of the three-party networks | te_ads_object.revenue |
| ecpm | TopOn calculates eCPM based on the Device Revenue( Revenue API split by the number of device impressions ) and TopOn statistics Device Impressions, calculated as ( Device Revenue / Device Impressions ) * 1000. Note: eCPM is delayed by 2 day | |
| is_abtest | control group or test group 0: control group or the A / B test is not activated, 1: test group | |
| traffic_group_id | control or test group id | |
| segment_id | segment id | |
| segment_name | segment name | |
| idfv | ios device id | |
| oaid | android device id | |
| user_id | developer's custom user id | |
| network_firm_id | network firm id | |
| network_firm | network name | te_ads_object.media_source |
| currency | account currency, USD means U.S. dollar, CNY means RMB | te_ads_object.currency |
| os_version | Operating system version of iOS device | |
| att_status | ATT status of iOS device: 0：Not determined, 1：Restricted, 2：Denied, 3：Authorize | |
| imei | android device id | |
| device_type | ios device type： 0: not ios device 1: iphone 2: ipad | |
| brand | name of the device brand | |
| model | device model | |
| app_vn | app version name | |
| app_vc | app version code | |
| new_user_type | type identified whether the device is a new user： 1: is a new user 2: not a new user | |
| channel | Channel, entered by the developer through the TopOn SDK | |
| estimate_revenue | Estimated revenue is calculated by summing up the real-time ad display prices of bidding ad sources. For non-bidding ad sources, the estimated revenue is calculated by multiplying the eCPM price manually filled in by TopOn with the display summary. |
# 4.4 User Properties Storage Rules
Currently, TopOn has not opened up user attribute storage rules.
# Data Storage Check
Finally, please check whether the TE system has received the TopOn data. You can check it by following these steps:
- Check whether the ta_ad_revenue_topon event has been created on the "Data Management" - "Meta-Events" page.
- You can also query whether ta_ad_revenue_topon has data in the event analysis model.