Singular SKAdNetwork API Reference

Learn how to use Singular's new API endpoints for SKAdNetwork reporting.

Note: The SKAdNetwork reporting endpoints are only available for customers of Singular's attribution service.

Looking for something else?

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.

Screen_Shot_2021-05-25_at_15.21.44.png

Screen_Shot_2021-05-25_at_15.22.00.png

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.

Create Async SKAdNetwork Report

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.

Screen_Shot_2021-05-25_at_15.21.44.png

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 Settings > API. 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 Derived from the IP that's included in the SKAdNetwork postback.
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."
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.

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.

Screen_Shot_2021-05-25_at_15.22.00.png

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 Settings > API. 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 The user's 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.
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_estimated_revenue
Revenue from campaigns that use a Revenue-type model. For more information, see What is Estimated Revenue and How is It Calculated?
skan_estimated_roi
ROI calculated based on skan_estimated_revenue.
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?

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 in 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 Settings > API. 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.

 

Was this article helpful?