-
Notifications
You must be signed in to change notification settings - Fork 44
stats api
/* Title: Understanding Advertising Statistics API Sort: 11 */
Note: The following documentation applies to the current API version; aspects of the domain and functionality are subject to change for general release.
The Statistics API is an HTTP interface that allows advertisers to retrieve acquisition statistics data in CSV format.
The Stats API now allows advertisers to start to receive SKadNetwork conversion value data. This supports using SKAd conversion values:
- as a
splitBy
dimension asskadConversionValue
- as a filter via the
skadConversionValues
parameter.
Using the Unity Ads Statistics API requires an API key token. You can generate an API key token from the Unity Dashboard by selecting API Management from the left navigation bar.
Note: The API key is generated for an specific username. If that username is removed from the organization, that API key will be automatically revoked. Please be aware of this if you use the API key as part of an integration with a 3rd party or any other business intelligence solution.
You can use the key token in two ways:
- Place the key token in the GET request URL
apikey
parameter. For example:
https://stats.unityads.unity3d.com/organizations/:organization_id/reports/acquisitions?apikey=<token>
- Place the key token in the
Authorization
header of the GET request, prefixed withBearer
. For example:
curl
https://stats.unityads.unity3d.com/organizations/:organization_id/reports/acquisitions -H "Authorization: Bearer <token>"
Make a GET request to the following example URL:
https://stats.unityads.unity3d.com/organizations/:organizationId/reports/acquisitions?splitBy=campaignSet,country&fields=timestamp,campaignSet,country,clicks,installs,spend&apikey=<token>
The following parameters define the period and scope of requested data:
Parameter | Description | Example |
---|---|---|
start |
Start time of the data query; required. | start={ISO 8601 timestamp} |
end |
End time of the data query; required. | end={ISO 8601 timestamp} |
scale |
Time resolution of the data (default is all ). |
|
Example time format: 2017-06-01T00:00:00.000Z
You can apply the following list of filters to your request:
Filter | Description | Example |
---|---|---|
campaignSets |
A comma-separated list of campaign set IDs to filter. | campaignSets=[:campaign_set_id] |
campaigns |
A comma-separated list of campaign IDs to filter. | campaigns=[:campaign_id] |
targets |
A comma-separated list of target game IDs to filter. | targets=[:target_id] |
adTypes |
A comma-separated list of ad types to filter. | adTypes=[(video)] |
countries |
A comma-separated list of country codes to filter (for example, US , FI , RU ). |
countries=[:country_code] |
stores |
A comma-separated list of app stores to filter. | stores=[(apple)] |
platforms |
A comma-separated list of platforms to filter. | platforms=[(ios)] |
osVersions |
A comma-separated list of operating system versions to filter (for example, 1.0.0 , 2.1.0 ). |
osVersions=[:os_version] |
creativePacks |
A comma-separated list of creative packs to filter. | creativePack=[:creativePack_id] |
sourceAppIds |
A comma-separated list of source app IDs to filter. This ID is an identifier derived from the game's app store page. Prior to migration, this was called source_id or source_game_id . This identifier is an alphanumeric, 12-character case-sensitive string. See notes. |
sourceAppIds=[:source_app_id] |
reachExtension |
A comma-separated list indicating external supply sources to filter. Possible values are unity and exchanges . |
reachExtension=[:exchanges] |
skadConversionValues |
A comma-separated list of SKAdNetwork conversion values to filter. These values must be integers between 0 and 63. | skadConversionValues=[:skad_conversion_value] |
In addition, you can specify a comma-separated list of dimensions by which to split data:
splitBy=[(campaignSet|creativePack|adType|campaign|target|sourceAppId|store|country|platform|osVersion|reachExtension|skadConversionValue)]
The following allows you to specify comma-separated fields to display in your report:
fields=[(timestamp|campaignSet|creativePack|adType|campaign|target|sourceAppId|store|country|platform|osVersion|starts|views|clicks|installs|spend)] (default:all)
Note: If you omit the fields parameter, all fields will be output. The default fields are:
timestamp|starts|views|clicks|installs|spend|cvr|ctr|ecpm|cpi
Note: The identifiers source_id
and source_game_id
have been deprecated. They have been replaced with SourceAppID
(source_app_id
). While the deprecated source_game_id was an integer, the identifier SourceAppID
(source_app_id
)is a case-sensitive, 12-character, alphanumeric string. For more information, please see the FAQs.
Field | Description |
---|---|
skadInstalls | Installs from Apple’s SKAdNetwork. |
skadCpi | CPI calculated based on installs from Apple’s SKAdNetwork. |
skadConversion | Conversion calculated based on installs from Apple’s SKAdNetwork. |
Notes:
- SKAd specific fields are not available by default in the response and therefore should be explicitly specified in the fields parameter if required.
- In addition, fields above will not be available for the creativePack, adType and osVersion filters since we do not get this granularity of data within the SKAd postbacks.
The data returns in CSV format, with the following delimiters:
- Commas (
,
) separate fields - Periods (
.
) indicate decimals - Double quotes (
" "
) indicate text fields - The newline character separates lines within a field
Split campaignSet
data results in two fields:
campaign set id
campaign set name
Split campaign
data results in two fields:
campaign id
campaign name
Split creativePack
data results in two fields:
creative pack id
creative pack name
Split target
data results in three fields:
target id
target store id
target name
Note: Splitting data by too many dimensions may impact response times for querying the API. To avoid lagging or timeouts, we recommend querying 1 day of data at a time when splitting by sourceAppId
and country
.
$ curl -L
"https://stats.unityads.unity3d.com/organizations/:organizationId/reports/acquisitions?splitBy=campaignSet,country&fields=timestamp,campaignSet,country,clicks,installs,spend&apikey=<token>"
timestamp,campaign set id,campaign set name,country,clicks,installs,spend
2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,"Campaign set #5",AU,71,30,45
2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,"Campaign set #5",CA,129,88,132
2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,"Campaign set#5",US,1745,855,1282.5
2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,"Campaign set#6",AT,39,19,28.5
2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,"Campaign set #6",AU,16,10,15
2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,"Campaign set #6",BE,209,120,180
$ curl -L
"https://stats.unityads.unity3d.com/organizations/:organizationId/reports/acquisitions?
splitBy=campaignSet,country&&skadConversionValues=2,3,4&fields=timestamp,campaignSet,country,clicks,installs,spend,skadInstalls,skadCpi,skadConversion&apikey=<token>"
timestamp,campaign set id,campaign set name,country,clicks,installs,spend,skad installs,skad cpi,skad conversion
2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,"Campaign set #5",AU,71,30,45,123,0.320683,0.017262
2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,"Campaign set #5",CA,129,88,132,1,2.537502,0.015625
2013-03-01T00:00:00.000Z,50ed569d57fe1f324a15fbf7,"Campaign set#5",US,1745,855,1282.5,242,1.492224,0.021007
2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,"Campaign set#6",AT,39,19,28.5,874,0.411434,0.017425
2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,"Campaign set #6",AU,16,10,15,2305,1.244165,0.038166
2013-03-01T00:00:00.000Z,50eeb7339e10c9d21c0225cb,"Campaign set #6",BE,209,120,180,234,0.469112,0.013641