ironSource data integration solution
Last updated: 2022-08-17
1. Overview
Note that data generated by third-party data integration counts toward the cluster's data consumption
This document describes how to send ironSource data back to Agentic Engine (hereinafter the AE system). This solution supports:
- Reporting data through the client SDK, which gets revenue data in real time. However, the revenue data is an estimate and differs slightly from the final settlement data
- Getting more accurate revenue data through the Impression Level Revenue API, but with lower timeliness (revenue data is available at T+1, and final data at T+2)
- Getting aggregated metric data, including impressions, revenue, and user activity, through the Reporting API.
Before you start connecting ironSource, 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.
2. Client SDK reporting
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| ILR SDK | Client SDKs | No | User level | Yes |
Impression Level Revenue (ILR) SDK API is the real-time revenue API of the ironSource SDK, available in ironSource client SDK (Android, iOS, Unity SDK) 7.0.3 and later. After an ad is displayed, this API gets estimated revenue data in real time through a callback. Combined with reporting through the AE client SDK, it gives you revenue data with very high timeliness.
2.1 ironSource configuration
To enable the real-time revenue postback feature of the ILR SDK, log in to the ironSource dashboard, and in the ARM SDK Postbacks section of the My Account > API page, select Enable ad revenue measurements (ARM) SDK postbacks
2.2 AE client SDK configuration
Option 1 (automatic integration):
If the AE SDK version you integrate is 2.8.0~2.8.1, we recommend the automatic association option
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 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 ironSource ID association
instance.enableThirdPartySharing(TDThirdPartyShareType.TD_IRON_SOURCE);
// Initialize the ironSource SDK
// ...
This option works by automatically registering the onImpressionSuccessEvent callback internally. After the callback is received, it automatically parses the parameters in IronSourceImpressionData and then sends the ta_ironSource_callback event through the AE SDK
Option 2 (manual integration):
For manual integration, you need to implement the ImpressionData Listener and add the AE SDK data reporting API in it. The following is a Unity code sample: implement ImpressionSuccessEvent() and attach it to onImpressionSuccessEvent, so that the callback is triggered after an ad is displayed and the data is reported. To learn how each SDK implements this, see the following links:
// Register ImpressionSuccessEvent and configure the logic for reporting data to AE in it
private void ImpressionSuccessEvent(IronSourceImpressionData impressionData) {
Debug.Log ("unity-script: ImpressionSuccessEvent impressionData = " + impressionData);
if (impressionData != null) {
Dictionary<string, object> properties = new Dictionary<string, object>()
{
// Revenue source: ad unit
{"adUnit", impressionData.adUnit},
// Revenue source: ad network
{"adNetwork", impressionData.adNetwork},
// Revenue source: ironSource instance name
{"instanceName", impressionData.instanceName},
// Revenue source: ironSource instance ID
{"instanceId", impressionData.instanceId},
// Placement
{"placement", impressionData.placement},
// Currency type
{"currency", "USD"},
// Revenue
{"revenue", impressionData.revenue},
// Revenue type
{"precision",impressionData.precision}
};
// Report the revenue data to AE, assuming the revenue event name is ironSource_sdk_postbacks
ThinkingAnalyticsAPI.Track("ironSource_sdk_postbacks", properties);
}
}
The following are the fields sent back by ironSource SDK Postbacks. You can also see the ironSource official documentation:
| Field name | Description | Data type |
|---|---|---|
| auctionId | Unique auction ID | String |
| adUnit | Displayed ad unit (such as Rewarded Video, Interstitial, Banner) | String |
| adNetwork | Ad network name | String |
| instanceName | Ad instance name | String |
| instanceId | Ad instance ID | String |
| country | Country (region) code in ISO 3166-1 format | String |
| placement | Ad placement | String |
| revenue | Revenue data (USD). This value may be an estimate. For details, see the value of the precision field | Double |
| precision | Source of the revenue value:
| String |
| ab | A/B Test label configured in the ironSource dashboard | String |
| segmentName | Name of the traffic segment the user is assigned to (that is, the Segment configured in the ironSource dashboard) | String |
| lifetimeRevenue | Cumulative revenue generated by the user | Double |
| encryptedCPM | This field exists only in ad data from Meta Audience Network (that is, Facebook Audience Network) | String |
3. Impression Level Revenue API
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Impression Level Revenue API | Pull | No | User level | Yes | Yes |
Impression Level Revenue API provides two types of data: impression-level and user-level. Each impression-level record is one ad impression, which fits the meaning of event data. User-level data aggregates a user's lifetime metrics, so it isn't suitable to send back as event data. Because this data keeps changing, it also isn't suitable for processing and analysis in the AE system. Therefore, we only support connecting impression-level data.
3.1 Get the authorization code and App Key
Before you connect Impression Level Revenue API, you need to get the authorization code and the App Key of the project to pull data from.
- Log in to the ironSource dashboard, click the user menu in the upper-right corner, go to the Reporting API tab of the My Account page, and send the Secret Key and Refresh Token to ThinkingAI staff:
- Next, go to the Ad Unit page of the ironSource dashboard and select the app you want to connect in the APPLICATIONS list. The card on the right shows the app's App Key. Send it to ThinkingAI staff or record it in the data integration configuration template (note that iOS and Android are separate. To connect data from both platforms, send two App Keys)
3.2 Client SDK configuration
To associate ironSource user data with the AE project, use the setUserId() method of ironSource to report the distinct ID of the AE user to ironSource. The following sample code uses the Unity SDK as an example to set the AE distinct ID as the ironSource UserId:
// Set the AE distinct ID as the ironSource User ID
IronSource.Agent.setUserId(ThinkingAnalyticsAPI.GetDistinctId());
The default distinct ID of the AE client SDK is as follows:
- On Android, the distinct ID of the AE SDK is the GAID, and advertising_id of ironSource takes the GAID
- On iOS, the distinct ID of the AE SDK is the IDFV; advertising_id of ironSource takes the IDFA/IDFV
3.3 Included fields
The following are the fields returned by Impression Level Revenue API:
- Dimension fields
| Field name | Description | Example value |
|---|---|---|
| event_timestamp | Impression timestamp | 2021-09-01 11:26:46 |
| #zone_offset | Time zone (AE preset property) | 0 (fixed value) |
| advertising_id | User's advertising ID (GAID / IDFA) | 137cf2f0-609c-4ae3-ab64-ed5c0d7392fd |
| advertising_vendor_id | User's vendor ID (app Set ID / IDFV) | A0810F0B-16C2-474B-B765-77B3A3113AA2 |
| user_id | User ID set by the user, that is, the user ID set in 3.2 | c7d9fed7-aa40-4bfa-918f-8d4b155bfd4b |
| ad_unit | Ad unit | rewarded_video |
| ad_network | Ad network | Admob |
| instance_name | Instance name | Bidding, High |
| country | Country (region) code | US |
| placement | Placement | Home_Screen |
| segment | Name of the traffic segment the user is assigned to | Tier 1 |
| AB_Testing | A/B Test label | A,B |
| app_key | App key | |
| app_name | App name | |
| platform | Platform | iOS, android |
- Metric fields
| Field name | Description | Example value |
|---|---|---|
| impressions | Impressions | 1000 |
| revenue | Revenue amount | 0.5 |
3.4 API parameters
-
Time:
-
Data is pulled by day in the UTC time zone
- Only data from the last 14 days can be pulled (for example, data for January 1 is retained until January 14 at the latest, and pulls after that return no data)
- Data for the previous day (UTC) is available at 2:00 PM UTC every day (10:00 PM Beijing time)
- Data corrections only apply to data from the last 2 days (that is, yesterday and the day before yesterday). After that, the data remains stable and is no longer adjusted
-
3.5 Data ingestion rules
By default, we write the pulled data into the AE project as events, one event per impression record:
- user_id in the data is used as the distinct ID of the data. This field should correspond to the distinct ID in the AE project
- The event_timestamp field in the data, that is, the ad impression time, is used as the event's #event_time
- The event name is ironsource_ad_revenue_impression_level
- All other fields are ingested
3.6 Data integration configuration template
After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:
Data interface: ironSource Impression Level Revenue 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
---------
secretkey: XXX
refreshToken: XXX
---------
Data pull configuration
appKey: XXX, XXX (separate for iOS and Android)
Time range for historical data pull: yyyy/mm/dd - yyyy/mm/dd (only data from the last 14 days can be pulled)
Scheduled pull: pull the previous day's data at 22:00 Beijing time every day
4. Reporting API
Basic interface information
| Interface | API type | Productized | Data granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|---|
| Reporting API | Pull | No | Aggregated metrics | Yes | Yes | Yes |
Reporting API is ironSource's aggregated metrics data API. You can use it to get aggregated metric data including impressions, revenue, and user activity.
4.1 Get the authorization code
Before you connect Reporting API, you need to get the authorization code. Log in to the ironSource dashboard, click the user menu in the upper-right corner, go to the Reporting API tab of the My Account page, and send the Secret Key and Refresh Token to ThinkingAI staff:
4.2 Included fields
The following are the fields returned by Reporting API:
- Dimension fields
The following are the analysis dimensions of Reporting API. Note that each analysis dimension supports different metrics. For the specific mapping, see the ironSource official documentation:
| Dimension name | Field name | Description | Default | Remarks |
|---|---|---|---|---|
| date | date | Data time | Yes | |
| adUnits | adUnits | Ad unit | Yes | |
app | appKey | App key | Yes | |
| bundleId | App ID | Yes | ||
| appName | App name | Yes | ||
| platform | platform | App platform | Yes | |
| adSource | providerName | Ad source | Yes | |
| instance | instanceName | Instance name | Mutually exclusive with segment, placement | |
| instanceId | Instance ID | |||
| country | countryCode | Country (region) code | Yes | |
| segment | segment | Name of the traffic segment the user is assigned to | Mutually exclusive with instance, placement | |
| placement | placement | Placement | Mutually exclusive with instance, segment | |
| osVersion | osVersion | OS Version | Choose at most one of the four | |
| connectionType | connectionType | Network connection type | ||
| sdkVersion | sdkVersion | SDK version | ||
| appVersion | appVersion | App version | ||
| att | att | ATT status | ||
| idfa | idfa | Whether IDFA is available | ||
| abTest | abTest | A/B Test label |
- Metric fields
The following is the list of metrics supported by Reporting API. Note that the available metrics are affected by the analysis dimensions, so you will actually receive fewer metrics than the table below shows:
| Field name | Description |
|---|---|
| revenue | Total revenue |
| eCPM | eCPM |
| appFillRate | Ad fill rate (impressions / requests) |
| appRequests | Ad requests |
| impressions | Impressions |
| completions | Completions
|
| revenuePerCompletion | Average revenue per completion (revenue / completions) |
| appFills | Ad fills |
| useRate | Ad impression-to-fill ratio |
| activeUsers | DAU |
| engagedUsers | Ad-engaged users |
| engagedUsersRate | Percentage of ad-engaged users |
| impressionsPerEngagedUser | Average ad impressions per ad-engaged user |
| revenuePerActiveUser | ARPU (in cents) |
| revenuePerEngagedUser | ARPU of ad-engaged users (in cents) |
| clicks | Total clicks |
| clickThroughRate | Click-through rate (CTR) |
| completionRate | Percentage of users who completed a specific action, that is, the conversion rate |
| adSourceChecks | Number of times ad sources checked ad availability |
| adSourceResponses | Number of responses from ad sources |
| adSourceAvailabilityRate | Ad availability rate (impressions / ad responses) |
| sessions | Sessions |
| engagedSessions | Sessions with ad engagement |
| impressionsPerSession | Average impressions per session |
| impressionPerEngagedSessions | Average impressions per session with ad engagement |
| sessionsPerActiveUser | Average sessions per user |
4.3 API parameters
- Time:
- Data is pulled by day in the UTC time zone
- App:
- You can specify the apps to pull (separate for Android and iOS)
4.4 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- Because Reporting 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 data time, is used as the event's #event_time
- The event name is ironsource_reporting_level
- All other fields are ingested
4.5 Data integration configuration template
After reading the documentation above, we recommend that you fill in the following template and send it to your customer success manager at ThinkingAI:
Data interface: ironSource Reporting 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
---------
secretkey: XXX
refreshToken: XXX
---------
Data pull configuration
Analysis granularity: xxx, xxx (leave blank to use the default)
App Keys to pull: xxx, xxx (all are pulled by default)
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
5. 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:
-
Events for the client SDK
- ta_ironSource_callback (option 1)
- ironSource_sdk_postbacks (option 2)
-
Events for Impression Level Revenue API
- ironsource_ad_revenue_impression_level
-
Events for Reporting API
- ironsource_reporting_level
6. FAQ
6.1 How does data reported by the client SDK differ from data reported by Impression Level Revenue API?
- Data reported by the client SDK is timely but less accurate
- Impression Level Revenue API data has a one-day delay and only becomes stable on the third day, so it is less timely, but it is highly accurate once the data stabilizes.
6.2 Why does the data ingested into AE differ slightly from the data in the ironSource dashboard UI?
- ironSource only supports pulling data in the UTC time zone. Check whether the time zone you set in the AE backend is UTC
- The slight difference may be caused by slight differences between the data pipeline of the ironSource API and that of the ironSource dashboard UI. For example, the UI data pipeline goes from database A to B, plus rounding logic for decimals in the frontend code, while the API data pipeline goes from database A to C;