TradPlus data integration solution
Last updated: 2022-08-22
1. Overview
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
This document describes how to send TradPlus ad monetization data back to Agentic Engine (hereinafter the AE system). This solution supports:
- Connecting user-level ad monetization data through the device-level data report API
- Connecting aggregated ad monetization data through the full report query API
Before you start connecting TradPlus, make sure you have read the AE system data rules and understand AE's data structure. We also recommend that you give the information needed to pull data to our customer success manager, using the format in the data integration configuration template.
Process
The TradPlus data integration process is as follows:
- Connect the device-level data report API
- Get the Token and app ID from the TradPlus dashboard and send them to ThinkingAI staff
- In the client SDK, set the distinct ID of the AE project as the TradPlus custom ID
- Determine the data dimensions, metric types, pull frequency, and time range to pull
- ThinkingAI staff complete the data pull development
- Build dashboards and reports in the AE backend, and complete data validation
- Full report query API
- Get the Token and app ID from the TradPlus dashboard and send them to ThinkingAI staff
- Determine the data dimensions, metric types, pull frequency, and time range to pull
- ThinkingAI staff complete the data pull development
- Build dashboards and reports in the AE backend, and complete data validation
2. Authorization
Whichever type of data you connect, you first need to log in to the TradPlus dashboard, get the Access Token and app ID, and send them to ThinkingAI staff.
- To get the Access token, go to My Account - Report API key in the TradPlus dashboard and click Generate key
- You can find the app ID under App Management - Apps & Placements
3. Device-level data report API
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Device-level data report API | Pull | No | User level | Yes | Yes | Yes |
The device-level data report API provides user-level ad monetization data, including metrics such as users' ad impressions, clicks, and revenue on a given day.
3.1 Configure the client SDK
To associate TradPlus ad data with the user data of the AE project, configure the client SDK to pass the distinct ID of the AE project to the TradPlus backend.
Option 1 (automatic integration):
If the AE SDK version you integrated is 2.8.0~2.8.1, you can use this option directly
If the AE SDK version you integrate is 2.8.2 or later, you also need to install the third-party data plugin
This option is an automatic integration option. After you initialize the AE client SDK, call the following code to enable it. For details, see the Android SDK third-party data and iOS SDK third-party data:
// Initialize the AE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// Enable TradPlus ID association
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_TRAD_PLUS);
// Initialize the TradPlus SDK
// ...
This option works by automatically calling the initCustomMap method of SegmentUtils internally to pass the distinct ID of the AE SDK into AppKeyManager.CUSTOM_USERID
Option 2 (manual integration):
With manual integration, you can use the AppKeyManager.CUSTOM_USERID (Android) or dicCustomValue (iOS) method of TradPlus to pass the AE distinct ID into userId of the TradPlus SDK (one of the parameters returned by the device-level data report API).
iOS code example:
//App-level custom information
NSString *ta_distinct_id = [instance getDistinctId];
[TradPlus sharedInstance].dicCustomValue = @{@"user_id": ta_distinct_id};
Android native code example:
String ta_distinct_id = instance.getDistinctId();
HashMap<String, String> customMap = new HashMap<>();
customMap.put(AppKeyManager.CUSTOM_USERID, ta_distinct_id);
//Set an app-level rule that applies to all placements
SegmentUtils.initCustomMap(customMap);
Unity SDK code example:
string ta_distinct_id = ThinkingAnalyticsAPI.GetDistinctId();
Dictionary<string, string> map = new Dictionary<string, string>();
map.Add("user_id", ta_distinct_id);
//Set an app-level rule that applies to all placements
TradPlus.initCustomMap(map);
Note (very important):
Reporting through AppKeyManager.CUSTOM_USERID (Android/Unity) or dicCustomValue (iOS) must be completed before the TradPlus SDK is initialized; otherwise, some userIds may not be sent back.
3.2 Data pull
3.2.1 Included fields
- Dimension fields
| Field | Type | Remarks |
|---|---|---|
| dateTimeStamp | int | Timestamp (date) |
| #zone_offset | int | Time zone, that is, the time zone used in the request |
| appId | String | App ID (TradPlus) |
| placementId | String | Ad placement ID (TradPlus) |
| placementName | String | Ad placement name (TradPlus) |
| adFormat | Int | Ad placement type |
| adFormatName | String | Ad placement type name |
| area | String | Country/region code (ISO 3166-1 two-letter country/region code) |
| network | Int | Ad network ID |
| networkName | String | Ad network name |
| networkPlacementId | String | Ad placement ID of the ad network |
| networkPlacementName | String | Ad source name of the ad network (TradPlus) |
| networkPlacementInfo | String | Ad placement details of the ad network |
| androidId | String | Device ID, androidid |
| gaid | String | Google advertising device ID |
| idfa | String | iOS device ID |
| userId | String | Custom User ID uploaded by the user; this should be the distinct ID of the AE project |
| channel | String | Channel |
| sub_channel | String | Sub-channel |
| oaid | String | Android device identifier |
| idfv | String | Identifier for vendor |
| os_version | String | OS version of the device |
| att_status | Int | Apple ATT status (0: not determined by the user; 1: restricted; 2: denied; 3: authorized) |
- Metric fields
| Field | Type | Remarks |
|---|---|---|
| impression | Int | Impressions (TradPlus) |
| click | Int | Clicks (TradPlus) |
| revenue | Float | Revenue |
| ecpm | Float | Revenue per 1,000 impressions |
3.2.2 API parameters
- Time:
- Data is pulled by day
- The time zone can be "UTC+8", "UTC+0", or "UTC-8"
- Data is pulled by day
- Currency:
- You can choose USD or CNY. The default is USD
- Project to pull:
- Specify the platform project to pull data from and provide the App ID of the project
3.2.3 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- userId in the data is used as the distinct ID of the data, and this field should correspond to the distinct ID in the AE project
- The dateTimeStamp field in the data, that is, the data timestamp, is used as the event's #event_time
- The event name is tradplus_device_report
- All other fields are stored
4. Full report query API
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Full report query API | Pull | No | Aggregated data | Yes | Yes | Yes |
The full report query API provides aggregated metric data for ad monetization, including metrics such as ad impressions, clicks, and revenue.
4.1 Analysis dimensions
The following are all the analysis dimensions of the full report query API. By default, we use all grouping dimensions. To adjust them, enter the grouping items to pull in the data integration configuration template.
| Grouping item | Field | Remarks |
|---|---|---|
| date | date | Date, in the format YYYY-mm-dd |
| appId | appId | App ID (TradPlus) |
| packageName | Package name | |
| placementId | placementId | Ad placement ID (TradPlus) |
| placementName | Ad placement name (TradPlus) | |
| adFormat | adFormat | Ad placement type |
| adFormatName | Ad placement type name | |
| area | area | Country/region code (ISO 3166-1 two-letter country/region code) |
| network | network | Ad network ID |
| networkName | Ad network name | |
| networkPlacementId | networkPlacementId | Ad placement ID of the ad network |
| networkPlacementName | Ad source name of the ad network (TradPlus) | |
| networkPlacementInfo | Ad placement details of the ad network |
4.2 Included metrics
The following are the metric fields included in the full report query API. By default, all fields are retrieved. To adjust them, enter the metric fields to pull in the data integration configuration template.
| Field | Type | Remarks |
|---|---|---|
| dau | Int | Daily active users (app level) |
| deu | Int | Daily users who watched ads |
| arpu | Float | Average revenue per user |
| newUsers | Int | New users (app level) |
| newUserRate | Float | Percentage of new users (app level) |
| requestApi | Int | Requests of the third-party ad platform |
| fillrateApi | Float | Fill rate of the third-party ad platform |
| impressionApi | Int | Impressions of the third-party ad platform |
| clickApi | Int | Clicks of the third-party ad platform |
| ctrApi | Float | Click-through rate of the third-party ad platform |
| ecpmApi | Float | eCPM of the third-party ad platform |
| revenue | Float | Revenue |
4.3 API parameters
- Time:
- Data is pulled by day
- The time zone can be "UTC+8", "UTC+0", or "UTC-8"
- Data is pulled by day
- Currency:
- You can choose USD or CNY. The default is USD
- Project to pull:
- You can specify the platform project to pull data from and provide the App ID of the project
4.4 Data 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 the data as attached to one virtual user
- The date field in the data, that is, the date of the data, is used as the event's #event_time
- The event name is tradplus_allreport
- All other fields are stored
5. Data integration configuration template
After reading the documentation above, fill in the APIs, fields, pull method, and other information you want to pull in the following template and send it to your customer success manager at ThinkingAI.
Interface: TradPlus device-level data report API / full report query API
--------
Company name: XXX
AE project environment: (SAAS/on-premises)
AE project name: XXX
AE project APP ID: XXX
Data receiving URL push_url: XXX
---------
TradPlus Access Token: XXX
---------
Data pull type: device-level data report API / full report query API (if you use both, fill them in separately)
<-----The following is for the device-level data report API----->
App ID in the TradPlus dashboard: XXX, XXX
Time zone of the pulled data: XXX (time zone; enum values: UTC-8, UTC+8, UTC+0; defaults to "UTC+0" if not passed)
<--------------------------------->
<-----The following is the information for the full report query API----->
App ID in the TradPlus dashboard: XXX, XXX
Time zone of the pulled data: XXX (time zone; enum values: UTC-8, UTC+8, UTC+0; defaults to "UTC+0" if not passed)
Analysis dimensions: XXX, XXX (all fields by default)
Metrics to pull: XXX, XXX (defaults to all, that is, all fields)
<------------------------------------>
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd
Scheduled pull: pull the previous day's data at X:00 every day
6. Integration testing and data usage
6.1 Data validation
On the Management > Events page or the SQL IDE page in the AE system backend, search for the following events to check whether they have been ingested:
- Device-level data report API: tradplus_device_report
- Full report query API: tradplus_allreport