menu
Is this helpful?

# 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

  1. Integrate TopOn client SDK (opens new window) and TE SDK, and set TE's user identification ID in TopOn SDK.
  2. Log in to the TopOn backend and obtain Publisher Key and APP Key.
  3. 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.
  4. 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)

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.