Unity Ads Advertising Statistics API V2.0
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 |
|---|---|---|---|---|---|---|---|---|
| Advertising Statistics API V2.0 | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ | ✅ |
This plan sends Unity Ads ad delivery data 2.0 back to Thinking Analytics (hereinafter the AE system) through the Advertising Statistics API v2.0. The plan supports:
- Sending basic report metrics from Unity Ads, such as cost, clicks, and impressions, back to the AE system
Integration process
- Log in to the Unity backend and get the Organization ID and API Key of the project whose data you want to ingest
- Log in to the AE backend, go to the Third-party Integration module, add a Unity integration plan, and complete the related configuration
- Check whether the AE system receives the data successfully, and build reports
1. Get the authorization information
1.1 Get the Organization ID
In the Unity Ads User Acquisition backend, select the Settings page under Administration in the left sidebar. In the Organization Settings table, find the Organization ID, then copy and save it.
1.2 Get the API Key and Secret
Next, you need to create a service account and assign it Advertise Stats API Viewer. Data can be pulled only with this account's API Key and Secret. The following shows the complete process, starting from creating the service account:
- Create a service account
In the Unity Cloud backend, go to the Administration > Service accounts page and click the create button in the upper-right corner to start creating a service account.
Then enter the service account name and description as needed, and finish creating the account.
- Create an authorization key
After the account is created, go to the account's settings page and create a new authorization key in the Keys section.
After the key is created, write down the Key ID, Secret Key, and Authorization header and keep them safe. You will use them when creating the integration plan.
- Set account permissions
Next, you need to grant the account the Advertise Stats API Viewer permission. In the Organization roles section, click to start creating a role and go to the permission selection page.
On the permission selection page, select Advertise Stats API Viewer under the Growth option to complete the permission settings.
2. Plan configuration
After you get the authorization information from the Unity backend, log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the configuration page of the Unity Ads Advertising Statistics API V2.0. Follow this section to create the plan:
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information and enter the information you obtained in the previous step in the pop-up:
Fill in all the information you got from the Unity backend. When you enter the Authorization header, include the Basic prefix at the beginning
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull Unity Ads Advertising Statistics API V2.0 data on a schedule. You can choose to pull data for a period of time at a specific time every day. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Receive Settings
You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.
2.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable; string type. |
| source | time_granularity | Time granularity of data pulling. Options:
|
| metrics | Metric fields of the corresponding API; list type; customizable | |
| group_by | Grouping dimensions in the data; list type; customizable | |
| transfer | double_columns | Metrics in the data; list type. These fields are ingested as numeric types when the data is received, and the other fields are ingested as strings (or time). We don't recommend changing it |
- Grouping dimensions
The following are the group-by dimensions supported by the Unity Advertising Statistics API V2.0. To adjust them, add the names of the dimensions you need to source.group_by
| Dimension name | Description | Ingested field name | Pulled by default |
|---|---|---|---|
| app | Group by App | app_id | Yes |
| app_name | Yes | ||
| campaign | Group by Campaign | campaign_id | Yes |
| campaign_name | Yes | ||
| country | Group by country (region) | country | |
| creativePack | Group by Creative Pack | creative_pack_id | Yes |
| creative_pack_name | Yes | ||
| creativePackType | Group by Creative Pack type | creative_pack_type | Yes |
| osVersion | Group by OS version | os_version | Yes |
| platform | Group by platform | platform | Yes |
| sourceAppId | Group by source game | source_app_id | |
| store | Group by app store | store | Yes |
targetGame | Group by target game | target_id | Yes |
| target_store_id | Yes | ||
| target_name | Yes | ||
| eventType | Group by Unity event type | event_type | |
| eventName | Group by Unity event name | event_name |
- Metric fields
In addition to the group-by dimensions, the Unity Ads Advertising Statistics API v2.0 also provides the following metric fields. To adjust them, add the names of the metrics you need to source.metrics.
| Metric name | Ingested field name | Field description | Pulled by default |
|---|---|---|---|
| timestamp | timestamp | Event time | Yes |
| starts | starts | Ad impressions | Yes |
| views | views | Completed ad views | Yes |
| clicks | clicks | Ad clicks | Yes |
| installs | installs | Installs after viewing the ad | Yes |
| spend | spend | Spend | Yes |
| cpi | cpi | Cost per install | |
| ctr | ctr | Click-through rate | |
| cvr | cvr | Conversion rate | |
| ecpm | ecpm | eCPM | |
| d[x]AdRevenue | d[x]_ad_revenue | Day N ad revenue | |
| d[x]AdRevenueRoas | d[x]_ad_revenue_roas | Day N ad revenue ROAS | |
| d[x]IapRevenue | d[x]_iap_revenue | Day N in-app purchase revenue | |
| d[x]IapRoas | d[x]_iap_roas | Day N in-app purchase ROAS | |
| d[x]Purchases | d[x]_purchases | Day N in-app purchases | |
| d[x]UniquePurchasers | d[x]_unique_purchasers | Day N first-time in-app purchasers | |
| d[x]Retained | d[x]_retained | Day N retained users | |
| d[x]RetentionRate | d[x]_retention_rate | Day N retention rate | |
| d[x]TotalRoas | d[x]_total_roas | Day N total ROAS | |
| d[x]LevelComplete | d[x]_level_complete | Day N users who completed a specific level | |
| d[x]CostPerLevelComplete | d[x]_cost_per_level_complete | Day N average cost per user who completed a specific level | |
| d[x]LevelCompleteRate | d[x]_level_complete_rate | Day N completion rate of a specific level |
In the table above, [x] can be replaced with actual numbers such as 0, 1, 3, 7, and 14. For example, d7 indicates the metric through day 7
2.5 Event ingestion rules
- The timestamp field in the data, that is, the time field of data aggregation, is used as the #event_time of the aggregated data
- If not renamed, the event name of the data is -- unity_ads_api_data
- All other fields are ingested
2.6 Standardized fields
The AE system standardizes some fields in Unity Ads Advertising Statistics API v2.0 data:
| Field | Standardized field | Description |
|---|---|---|
| campaign_name | te_ads_object.campaign_name | Campaign name |
| campaign_id | te_ads_object.campaign_id | Campaign ID |
| creative_pack_name | te_ads_object.ad_group_name | Ad group name |
| creative_pack_id | te_ads_object.ad_group_id | Ad group ID |
| country | te_ads_object.country | Country or region code |
| platform | te_ads_object.platform | Platform, such as Android or iOS |
| starts | te_ads_object.impressions | Impressions |
| clicks | te_ads_object.clicks | Clicks |
| installs | te_ads_object.installs | Conversions (installs) |
| spend | te_ads_object.cost | User acquisition cost |