[NEW] Singular SKAdNetwork Reporting API

Learn about Singular's two new API endpoints for SKAdNetwork reporting:

  • create_async_skadnetwork_raw_report: Use this endpoint to analyze the raw SKAdNetwork install data as received in SKAdNetwork postbacks.
  • create_async_skadnetwork_report: See SKAdNetwork data combined with ad network cost and impressions stats and CPI calculation. 

Looking for something else?

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.

Note: 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 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 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 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.

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.

Note: 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 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.
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.
custom_impressions Number of ad views. This is the same metric used in regular (non-SKAdNetwork) Singular reporting. By default, this metric is taken from ad network data, but it can be set up to be based on tracker data.
custom_clicks Number of ad clicks. This is the same metric used in regular (non-SKAdNetwork) Singular reporting. By default, this metric is taken from tracker data, but it can be set up to be based on ad network data.
tracker_installs 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_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.
ctr Click-through rate (ratio of clicks to impressions).
skan_ocvr Conversion rate from impressions to SKAN installs.
skan_ecpi Effective Cost per Install: the total cost divided by the number of SKAN 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?