ironSource Reporting API
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 |
|---|---|---|---|---|---|---|---|---|
| Reporting API | API | Aggregated metrics | ✅ | ✅ | ✅ |
Reporting API is ironSource's aggregated metrics data API. You can use it to get aggregated metric data including impressions, revenue, and user activity.
Integration process
- Log in to the ironSource dashboard and get the App Key, Secret Key, and Refresh Token
- Log in to the AE backend, go to the Third-party Integration module, add an ironSource Reporting API plan, and complete the related configuration
- Check whether the AE system receives the data successfully, and build reports
1. Get the authorization information
First, log in to the ironSource dashboard to get the necessary authorization information
- First, click the user menu in the upper-right corner, go to the Reporting API tab of the My Account page, and get the Secret Key and Refresh Token
- 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. Note it down (iOS and Android are separate. To connect data from both platforms, configure two plans and enter the respective App Keys)
2. Plan configuration
After you get the authorization information, log in to the AE system backend and configure ironSource Reporting API in the Third-party Integration module. The image below shows the ironSource configuration page:
2.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
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull ironSource Reporting API data 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
2.3 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.
2.4 Configuration
In the Configuration module, you can control the detailed settings of data pulling, such as the event name after ingestion, the metrics to pull, and the optional dimensions.
The configuration is a JSON, and you can adjust its content as needed
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable |
| source | metrics | Metrics in the data; list type; customizable |
| group_by | Grouping dimensions in the data; list type; customizable |
- Optional dimensions
The following are the optional dimensions of the Reporting API. Note that each analysis dimension supports different metrics. For the specific mapping, see the ironSource official documentation. To change them, enter the names of the dimensions you need in source.group_by
| Dimension name | Ingested 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 the Reporting API. By default, we pull all fields. Note that the available metrics depend on the analysis dimensions, so you may receive fewer metrics than listed in the table below. To change them, enter the names of the fields you need in source.metrics
| 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 | Completion 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 |
2.5 Event ingestion rules
- 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
2.6 Standardized fields
The following event properties are standardized:
| Original field | Standardized field | Description |
|---|---|---|
| providerName | te_ads_object.media_source | Monetization channel |
| adUnits | te_ads_object.ad_group_name | Unit name of the monetization ad |
| placement | te_ads_object.placement | Ad placement |
| countryCode | te_ads_object.country | Country or region code |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| bundleId | te_ads_object.app_id | App ID |
| appName | te_ads_object.app_name | App name |
| impressions | te_ads_object.impressions | Impressions |
| clicks | te_ads_object.clicks | Clicks |
| revenue | te_ads_object.revenue | Monetization revenue |