Update [April 2022]:
- In the SKAdNetwork report, we recommend querying for the skan_revenue and skan_roi metrics. Tthe older skan_estimated_revenue and skan_estimated_roi will be deprecated in the future.
- skan_revenue contains all revenue gained, regardless of the source (IAP or ad mon) and regardless of what conversion model was used.
Note: This is a guide and reference material for using an API interface to get SKAdNetwork data. These API endpoints are available to customers using Singular's attribution tracker.
- For SKAdNetwork reporting in the Singular web app, see the SKAdNetwork Reporting FAQ.
- For Singular's Reporting API that is not SKAdNetwork-specific, see Getting Started with the Singular Reporting API and the Reporting API Reference.
- If you are a Singular partner, you may be looking for the Get SKAN Conversion Info API Reference (SKadNetwork API for Singular Partners).
How to Use the SKAdNetwork API
1 |
Query the Create Async SKAdNetwork Raw Report endpoint or the Create Async SKAdNetwork Report endpoint, specifying the metrics and dimensions you've chosen. This will generate an asynchronous report query and returns a report ID. Note: If you want to get data about SKAdNetwork events, query the SKAN Events endpoint first to get a list of your available SKAN events. |
2 |
Using the report ID, query the Get Report Status endpoint to see when the report has finished running. When the report is done, the Get Report Status endpoint returns a report URL. |
3 |
Download the report from the report URL. |
List of SKAdNetwork API Endpoints
The following API endpoints are available:
Create Async SKAdNetwork Raw Report | POST | https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report | Use this endpoint to analyze the raw SKAdNetwork install data as received in SKAdNetwork postbacks. |
POST | https://api.singular.net/api/v2.0/create_async_skadnetwork_report | See SKAdNetwork data combined with ad network cost and impressions stats and CPI calculation. | |
SKAN Events | GET | https://api.singular.net/api/v2.0/skan_events | This helper endpoint returns a list of your available SKAN events, to use when querying Create Async SKAdNetwork Report. |
Get Report Status (same endpoint used for Non-SKAN Reports) | GET |
https://api.singular.net/api/v2.0/get_report_status | Returns the status of a given report. |
Create Async SKAdNetwork Raw Report Endpoint
POST | https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report |
Usage
This endpoint generates an asynchronous report query for raw SKAdNetwork data, which is the data collected from SKAdNetwork postbacks. Query this endpoint to see the number of SKAdNetwork conversions per network and app. You can also break down the conversions by conversion value, where available - the actual number from 0 to 63 is a dimension in this report. See full details below.
The endpoint returns a Report ID. The next step is to query the Get Report Status endpoint to see when the report is done and get a download URL.
Sample Query (Python)
import requests
url = "https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report"
params = {"api_key": API_KEY}
data = {
"skadnetwork_date_type": "skan_postback_date",
"start_date": "2021-01-01",
"end_date": "2021-01-01",
"dimensions": "app,source,skan_network_id,skan_campaign_id,skan_app_id,skan_publisher_id,skan_conversion_value,skan_redownloads,skan_validated,country_field",
"metrics": "skan_installs",
"filters": '[{"dimension": "skan_validated", "operator": "in", "values": ["false"]},{"dimension": "skan_redownloads", "operator": "in", "values": ["true"]}]',
"time_breakdown": "all",
}
response = requests.post(url=url, params=params, data=data)
Query Parameters
Parameter | Format | Description | Example |
Basic Parameters | |||
api_key | String | All Singular API requests require an API key. To retrieve the key, log into your account and go to Developer Tools > API Keys. You can insert the key in the api_key parameter in your request or provide the token under an Authorization HTTP header. | |
start_date | Date | '2020-12-01' | |
end_date | Date | '2020-01-10' | |
time_breakdown | String | How to break down the results: - "day" - "week" - "month" - "all" (display aggregated data over the entire date range) |
'all' |
skadnetwork_date_type | String | Choose which type of date you want the report to be based on: - "skan_postback_date" (default) - the date the SKAN postback was sent by the device. - "estimated_install_date" - the install date as calculated by Singular (see How does Singular calculate the install date?). |
'estimated_install_date' |
Field Selection Parameters | |||
dimensions | String | A comma-separated list of dimensions. See the table below for the dimensions available for SKAdNetwork reports. | |
metrics | String |
A comma-separated list of metrics. See the table below for the metrics available for SKAdNetwork reports. |
'skan_installs' |
Filtering Parameters | |||
app | String | A comma-separated list of app names to filter the query results by. To retrieve a list of app names, use the Filters endpoint. | 'my_app1, my_app2' |
source | String | A comma-separated list of ad networks (and other sources) to filter by. To retrieve a list of ad network names, use the Filters endpoint. | 'facebook,adwords' |
filters | An array of JSON objects where each object contains a dimension, an operator, and a value to filter by. Use this parameter to apply more advanced filtering. Note that if you specify more than one filter, they will be applied with an AND relation. Available filters for SKAdNetwork reports (see details in the Available Dimensions table below) "country_field" "skan_redownloads" "skan_validated" |
'[{"dimension": "skan_validated", "operator": "in", "values": ["false"]}, {"dimension": "skan_redownloads", "operator": "in", "values": ["true"]}]' |
|
Formatting Parameters | |||
format | String | The format in which the query results will be delivered. Options: "json" (default) or "csv". | 'csv' |
country_code_format | String | Either "iso3" (default) or "iso" | 'iso' |
Available Dimensions
Dimension | Description |
skan_app_id | The value of the 'app-id' parameter in Apple's SKAdNetwork postback. |
skan_network_id | The value of the 'ad-network-id' parameter in Apple's SKAdNetwork postback. |
skan_campaign_id | The value of the 'campaign-id' parameter in Apple's SKAdNetwork postback. |
skan_publisher_id | The value of the 'source-app-id' parameter in Apple's SKAdNetwork postback. |
app | The app name in Singular (derived from skan_app_id). |
source | The ad network name as listed in Singular (derived from skan_network_id). |
tracker_campaign_id |
The Campaign ID as used in regular Singular reports (not the campaign ID given by SKAdNetwork). |
tracker_campaign_name |
The Campaign Name as used in regular Singular reports. |
country_field |
Since SKAdNetwork currently does not provide geographical data for the user, Singular attempts to fill in this information by looking at the network's campaign targeting settings. This field is populated only if the campaign was targeted to a single country. |
skan_conversion_value | The SKAdNetwork conversion value (a number between 0 and 63). |
skan_redownloads | Apple's SKAdNetwork postbacks include a "redownload" field. According to Apple, this is set to true if the app has already been downloaded and installed by the same user (same Apple ID). Singular marks every SKAdNetwork install accordingly as either a "download" or a "redownload." Important: For SKAdNetwork installs reported by Facebook and Snapchat, the "redownload" field in Singular is always false, because Facebook and Snapchat don't share the value of this field with customers or MMPs. This may cause discrepancies between redownload numbers in Facebook/Snapchat vs. Singular reporting. |
skan_validated | As a part of Singular's SKAdNetwork solution, Singular not only receives and parses SKAdNetwork postbacks from ad networks but also checks with Apple to confirm that each postback represents an actual install. Validation ensures that installs are not fraudulent. |
Available Metrics
Metric | Description |
skan_conversion_values_count | The number of SKAN installs for which Singular has received a conversion value (including conversion value 0 but not including conversion value Null). |
skan_conversion_values_ratio | The percentage of SKAN installs for which Singular has received a conversion value (including conversion value 0 but not including conversion value Null). This is equal to Conversion Values Count / SKAN Installs. |
skan_installs | The number of installs as reported by the SKAdNetwork framework. |
modeled_skan_conversion_values_count |
The number of SKAN installs that Singular estimates will have a conversion value (including conversion value 0 but not including conversion value Null). Use this along with the Conversion Value dimension to understand how many installs had a specific conversion value, e.g. if you see a count of 1000 with a conversion value of 3, that means we estimate 1000 installs had a conversion value of 3. |
Create Async SKAdNetwork Report Endpoint
POST | https://api.singular.net/api/v2.0/create_async_skadnetwork_report |
Usage
This endpoint generates an asynchronous report query for SKAdNetwork data merged with ad network and tracker data. Query this endpoint to measure CPI, click-through rate, etc., for your SKAdNetwork campaigns, broken down by network and/or campaign.
The endpoint returns a Report ID. The next step is to query the Get Report Status endpoint to see when the report is done and to get a download URL.
Sample Query (Python)
import json
import requests
url = "https://api.singular.net/api/v2.0/create_async_skadnetwork_report"
params = {"api_key": <API_KEY>}
data = {
"format": "csv",
"skadnetwork_date_type": "estimated_install_date",
"start_date": "2021-03-10",
"end_date": "2021-03-10",
"dimensions": "app,country_field,source,unified_campaign_id,unified_campaign_name",
"metrics": "custom_impressions,custom_clicks,tracker_installs,adn_cost,skan_installs,ctr,skan_ocvr,skan_ecpi",
"time_breakdown": "all"
}
response = requests.post(url=url, params=params, data=data)
Query Parameters
Parameter | Format | Description | Example |
Basic Parameters | |||
api_key | String | All Singular API requests require an API key. To retrieve the key, log into your account and go to Developer Tools > API Key. You can insert the key in the api_key parameter in your request or provide the token under an Authorization HTTP header. | |
start_date | Date | '2020-12-01' | |
end_date | Date | '2020-01-10' | |
time_breakdown | String | How to break down the results: - "day" - "week" - "month" - "all" (display aggregated data over the entire date range) |
'all' |
skadnetwork_date_type | String | Choose which type of date you want the report to be based on: - "skan_postback_date" (default) - the date the SKAN postback was sent by the device. - "estimated_install_date" - the install date as calculated by Singular (see How does Singular calculate the install date?). |
'estimated_install_date' |
Field Selection Parameters | |||
dimensions | String | A comma-separated list of dimensions. See the table below for the dimensions available for SKAdNetwork reports. | |
metrics | String | A comma-separated list of metrics. | 'skan_installs' |
skan_events |
String | A comma-separated list of SKAN events for which you want to see event counts. Specify the events by their automatically assigned 'name', not their 'display_name'. For a list of available events, query the SKAN Events endpoint. | '283465926592873, 394753947523452' |
Formatting Parameters | |||
format | String | The format in which the query results will be delivered. Options: "json" (default) or "csv". | 'csv' |
Available Dimensions
Dimension | Description |
source | The partner network. |
app | The app name. |
country_field | Since SKAdNetwork currently does not provide geographical data for the user, Singular attempts to fill in this information by looking at the network's campaign targeting settings. This field is populated only if the campaign was targeted to a single country. |
skan_redownloads | Apple's SKAdNetwork postbacks include a "redownload" field. According to Apple, this is set to true if the app has already been downloaded and installed by the same user (same Apple ID). This dimension breaks down the installs by whether they are a "redownload" or a regular download. Important: For SKAdNetwork installs reported by Facebook and Snapchat, the "redownload" field in Singular is always false, because Facebook and Snapchat don't share the value of this field with customers or MMPs. This may cause discrepancies between redownload numbers in Facebook/Snapchat vs. Singular reporting. |
skan_validated | As a part of Singular's SKAdNetwork solution, Singular not only receives and parses SKAdNetwork postbacks from ad networks but also checks with Apple to confirm that each postback represents an actual install. Validation ensures that installs are not fraudulent. This dimension breaks down the installs by whether they were successfully validated. Note that for some networks' data, e.g., Facebook, Singular can't validate SKAdNetwork installs, and they are instead assumed to have been validated by Facebook. |
unified_campaign_id | The Campaign ID as used in regular Singular reports (not the campaign ID given by SKAdNetwork). |
unified_campaign_name | The Campaign Name as used in regular Singular reports. |
Available Metrics
Metric | Description |
adn_cost | Cost as reported by the ad network. |
ctr | Click-through rate (ratio of clicks to impressions). |
skan_conversion_values_count | The number of SKAN installs for which Singular has received a conversion value (including conversion value 0 but not including conversion value Null). |
skan_conversion_values_ratio | The percentage of SKAN installs for which Singular has received a conversion value (including conversion value 0 but not including conversion value Null). This is equal to Conversion Values Count / SKAN Installs. |
skan_revenue |
Any campaign revenue (regardless of the conversion model used). Note: This metric replaces the older skan_estimated_revenue. |
skan_roi |
ROI calculated based on skan_revenue. Note: This metric replaces the older skan_estimated_roi. |
skan_installs | Number of installs as reported by SKAdNetwork. |
skan_ecpi | Effective Cost per Install: the total cost divided by the number of SKAN installs. |
skan_ocvr | Conversion rate from impressions to SKAN installs. |
skan_report_network_clicks |
Ad clicks, as reported by the network. |
skan_report_network_impressions |
Ad impressions, as reported by the network. |
tracker_installs | The number of installs. These are installs that were attributed by the tracker based on device matching, as opposed to "SKAN Installs," which are based on SKAdNetwork postbacks. See What are tracker installs? |
With the introduction of SKAN Advanced Analytics, the Report Endpoint now supports modeled metrics and events. To request a modeled metric or event, append "modeled_" at the start of a metric or event parameter.
We also support confidence intervals for each modeled parameter. To request a confidence interval, append "_confidence_interval" at the end of a modeled metric or event parameter.
SKAN Events Endpoint
GET | https://api.singular.net/api/v2.0/skan_events |
Usage
This endpoint returns a list of your available SKAN events, for use when querying Create Async SKAdNetwork Report. The events are displayed as pairs of "display_name" and "name." "display_name" is the name of the event as it appears on the Events page, while "name" is the automatically assigned ID that you need to specify when you query Create Async SKAdNetwork Report.
For more information, see What are "SKAN Events"?
Sample Query (Python)
import requests
import json
url = "https://api.singular.net/api/v2.0/skan_events"
params = {'api_key': <API_KEY>}
result = requests.get(url=url, params=params)
print result.json()
Query Parameters
Parameter | Format | Description | Example |
api_key | String | All Singular API requests require an API key. To retrieve the key, log into your account and go to Developer Tools > API Keys. You can insert the key in the api_key parameter in your request or provide the token under an Authorization HTTP header. |
Sample Response
{
u'status': 0,
u'substatus': 0,
u'value': {
u'skan_events': [
{u'display_name': u'level_up', u'name': u'845736495863948'},
{u'display_name': u'tutorial_watched', u'name': u'34079384570293'},
{u'display_name': u'facebook_login', u'name': u'283462837462348'}
]
}
}
SKAN-Specific Error Codes
Singular uses standard HTTP response codes to indicate the success or failure of an API request. In general, 200 codes correspond to success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and 5xx codes are for other issues.
See also: List of general error codes returned by the Reporting API
Error message | Solution |
There is no SKAdNetwork data configured. | |
'is_skadnetwork_report' param expected to receive value 'true', got 'xxx' instead | Make sure your parameter values match the permitted values listed in the table above. |
'skadnetwork_date_type" param expected to receive one of the following values (...), got '...' instead. | |
The dimensions ['...'] can not be requested in an SKAdNetwork report. | |
The metrics ['...'] can not be requested in an SKAdNetwork report. | |
The '...' filter expected to receive one of the following values ['false,' 'true', got '...' instead. |