[NEW] Singular SKAdNetwork Reporting API

Learn how to use the Singular API to pull your SKAN (SKAdNetwork) data.

 

Note: All Singular API requests require an API key. To retrieve the key, log into your account and go to Settings > API. You can insert the key in the api_key parameter in your request, or provide the token under an Authorization HTTP header.

Create Async SKAdNetwork Report Endpoint

POST https://api.singular.net/api/v2.0/create_async_skadnetwork_raw_report

Usage

This endpoint generates an asynchronous report query for Singular SKAdNetwork data and 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 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 API key provided in the Singular console  
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 are.  
metrics String A comma-separated list of metrics. The only metric available for SKAdNetwork reports at this point is skan_installs. '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 it is listed in Singular (derived from skan_network_id).
country_field Derived from the IP that's included in the SKAdNetwork postback.
skan_conversion_value  
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".
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.

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.

 

Was this article helpful?