Learn how to become an integrated partner of Singular’s SKAdNetwork solution. See also: Integrating with Singular Attribution, which is a separate and required integration.
If you are a Singular customer, see Singular's SKAdNetwork Solution instead.
What is SKAdNetwork?
Apple's introduction of App Tracking Transparency limits the use of traditional user-level mobile measurement. Starting early 2021 (see Apple's September 3rd, 2020 update), the iOS Advertising Identifier (IDFA) will be available only for end-users who consent to share their data (opt-in). In markets that use iOS devices heavily, advertisers who continue to rely on traditional methods to measure their campaigns will receive only a portion of their campaign performance data.
The alternative offered by Apple is SKAdNetwork, a privacy-centric framework for aggregate campaign measurement, which was originally introduced with iOS 11.3 but has been updated significantly for iOS 14 (SKAdNetwork version 2.0).
Ad network partners who are registered with SKAdNetwork can receive automatic "SKAdNetwork postbacks" when there is an app install, whether the end-user opted in to sharing their data or not.
Why should I integrate Singular's SKAdNetwork solution?
September 3rd, 2020 Update: While Apple has announced a delay for privacy features and updates to the behavior of App Tracking Transparency, the answer below is still relevant. IDFA will remain available for "traditional" tracking until "early next year," but Apple still intends to push toward privacy-centric measurement via SKAdNetwork.
Singular is dedicated to helping partners integrate with SKAdNetwork as soon as possible in preparation for when advertisers will be reliant on the new tracking solution. The delay provides a valuable opportunity for the industry to fully understand SKAdNetwork data alongside IDFA-based attributions. For more, see our post in the Singular blog.
SKAdNetwork decentralizes key performance data between advertisers, publishers, ad networks, and mobile measurement providers, making it more difficult for advertisers to access the performance data that they need to make marketing decisions.
Singular's SKAdNetwork solution, SKAN, gathers the data that advertisers need using an information exchange between the end-user's device, the ad network, and Singular (as the MMP).
- The SKAdNetwork postback is sent from the device to the ad network + to the MMP.
- The conversion value and its meaning are sent from the MMP to the ad network.
- The campaign ID and its meaning are sent from the ad network to the MMP.
Data flow diagram for Singular's Secure SKAN
What is involved in integrating Singular's SKAdNetwork solution?
1. Registering With SKAdNetwork
Ad network partners must register with Apple as a prerequisite to using SKAdNetwork. Apple will assign the partner an "ad network ID".
2. Handling the SKAdNetwork Postback
Option A (Recommended): Secure SKAN
Method | 307 Redirect |
Redirect URL | https://skadnetwork.singular.net/api/v1/skan_postback |
Use a 307 redirect to allow Singular to receive the same SKAdNetwork postback sent from the device.
When you receive a SKAdNetwork postback for an advertiser who uses Singular as their MMP, use a 307 redirect to allow Singular to receive the same postback. Redirect the postback to Singular's dedicated skan_postback endpoint.
The redirect should also include some additional parameters in the URL (refer to the Ad Network fields). Here is an example for a full URL you could redirect the postback to:
"https://skadnetwork.singular.net/api/v1/skan_postback?adn_campaign_id=102&adn_campaign_name=My%20Campaign"
See the parameter reference for more details.
Option B: Sending the contents of the SKAdNetwork postback to Singular
Method | POST request |
Endpoint URL |
https://skadnetwork.singular.net/api/v1/skan_postback |
Payload | Entire payload postback received from SKAdNetwork. |
As an ad network partner, you can use the skan_postback endpoint to send Singular a postback containing the entire payload of the postback from SKAdNetwork, unmodified. The postback should also contain some additional parameters.
The postback sent to Singular may look as follows:
{
"version": "2.0",
"ad-network-id": "com.example",
"campaign-id": 42,
"transaction-id": "6aafb7a5-0170-41b5-bbe4-fe71dedf1e28",
"app-id": 525463029,
"attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk\/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO\/oU1AXUROYU=",
"redownload": 1,
"source-app-id": 1234567891,
"conversion-value": 20,
"skan_ip": "136.25.2.194",
"skan_timestamp": 1601555400,
"adn_campaign_id": "102",
"adn_campaign_name": "My Campaign"
}
See the parameter reference for more details.
3. Decode the SKAdNetwork Conversion Value
After you send Singular an SKAdNetwork postback using one of the methods above, you may want to decode the meaning of the conversion value. Singular can support this in two ways.
Option A: Conversion Event Postback
Singular can send you back a notification postback containing information about the SKAdNetwork conversion event.
The goal is for you to save and process the conversion information, just like you do with postbacks that Singular sends about identifier- or fingerprint-based attributions and events.
Singular will work with your team to learn which endpoint you want the postbacks sent to and to configure a postback template that is convenient for you to process.
As an example, a postback that Singular sends to a partner could look like this (with Singular postback macro syntax):
{
"transaction-id": {SKAN_POSTBACK.TRANSACTION_ID},
"conversion_event":{CONVERSION.PARTNER_CONVERSION_NAME},
"is_attributed":{SKADNETWORK_IS_VALID},
"original-conversion-value":{SKAN_POSTBACK.CONVERSION_VALUE},
"mmp-conversion-name":{CONVERSION.ADVERTISER_CONVERSION_NAME},
"mmp-conversion-value":{CONVERSION.ADVERTISER_CONVERSION_VALUE},
"mmp-conversion-currency":{CONVERSION.ADVERTISER_CONVERSION_CURRENCY},
"advertiser-app":{SKAN_POSTBACK.APP_ID},
"attribution-type":"skadnetwork",
"mmp":"singular"
}
See the reference section for all macros available with SKAdNetwork conversion event postbacks.
Option B: Use the SKAN Conversion Info API (Limited Release)
Singular also hosts a pull API that allows integrated partners to retrieve the conversion model mapping. This
This API simply returns the configured conversion model for a given app(s), provided the following requirements have been met:
- Advertiser app has an active configured Conversion Model
- Advertiser has an active Partner Configuration created for the partner
- Partner has access to the Partner Portal to retrieve an API Key
See our supporting technical documentation for this API for more information on request/response specifications and examples.
4. Handling the Campaign ID
If you use the Secure SKAN method to report SKAdNetwork postbacks to Singular, you can pass the information to Singular via your analytics integration with Singular.
I want to integrate with Singular's SKAdNetwork solution. Where do I start?
- Prerequisites:
- Ensure your ad network is already integrated with Singular attribution.
- Register for SKAdNetwork and have an "ad network ID" issued by Apple.
- Gather requirements: Review What is a Singular SKAdNetwork Integration? to understand the integration details and options available.
- Fill out the integration form for Singular's SKAdNetwork solution.
- Receive our integration team's reply: The Singular integration team will review your form and let you know if we have any questions or if we have all the information we need.
-
Test the Integration: After Singular finishes creating the integration, we will contact you to let you know how you can test the integration on your end.
Reference: SKAdNetwork Postback Parameters
This section documents the API endpoint and parameters that Singular supports for inbound SKAdNetwork postbacks to Singular (device → Singular, Ad Network → Singular).
Endpoint: https://skadnetwork.singular.net/api/v1/skan_postback
Method: POST
Parameters:
*indicates a required value
Source | Parameter | Parameter Description | Type |
SKAdNetwork | version * | The "version" from the SKAdNetwork postback Required with SKAdNetwork version 2.0 |
String |
SKAdNetwork | ad-network-id * | The "ad-network-id" from the SKAdNetwork postback | String |
SKAdNetwork | transaction-id * | The "transaction-id" from the SKAdNetwork postback | String |
SKAdNetwork | campaign-id * | The "campaign-id" from the SKAdNetwork postback | Integer |
SKAdNetwork | app-id * | The "app-id" from the SKAdNetwork postback | Integer |
SKAdNetwork | attribution-signature * | The "attribution-signature" from the SKAdNetwork postback | String |
SKAdNetwork | redownload * | The "redownload" from the SKAdNetwork postback Required with SKAdNetwork version 2.0 |
Integer |
SKAdNetwork | source-app-id * | The "source-app-id" from the SKAdNetwork postback Required with SKAdNetwork version 2.0 |
Integer |
SKAdNetwork | conversion-value * | The "conversion-value" from the SKAdNetwork postback Required when sent with SKAdNetwork version 2.0 |
Integer |
Ad Network | skan_timestamp * | The Unix formatted (seconds) timestamp when the SKAdNetwork postback was received. | Integer |
Ad Network | skan_ip * | The IP address of the sender from the SKAdNetwork postback | String |
Ad Network | adn_campaign_id * | The ID of the campaign | String |
Ad Network | adn_campaign_name * | The name of the campaign | String |
Ad Network | adn_creative_id | The creative ID | String |
Ad Network | adn_creative_name | The creative name | String |
Ad Network | adn_sub_campaign_id | The ID of the sub-campaign. May also represent the "ad group" or "ad set". | String |
Ad Network | adn_sub_campaign_ name | The name of the sub-campaign. May also represent the "ad group" or "ad set". | String |
Ad Network | adn_sub_adnetwork_ name | The sub ad network, which may represent an additional level of ad network hierarchy | String |
Reference: Conversion Event Postback
Request Specifications (Singular → Ad Network)
This section documents available values that Singular can include in SKAdNetwork conversion event postbacks from Singular to partners. These values are intended to provide conversion value information to the ad network.
The values are available in both GET and POST payloads.
Source | Value | Value Description | Type |
SKAdNetwork | {SKAN_POSTBACK.VERSION} | The "version" from the SKAdNetwork postback Available with SKAdNetwork version 2.0 |
String |
SKAdNetwork | {SKAN_POSTBACK. AD_NETWORK_ID} | The "ad-network-id" from the SKAdNetwork postback | String |
SKAdNetwork | {SKAN_POSTBACK. CAMPAIGN_ID} | The "campaign-id" from the SKAdNetwork postback | Integer |
SKAdNetwork | {SKAN_POSTBACK. TRANSACTION_ID} | The "transaction-id" from the SKAdNetwork postback | String |
SKAdNetwork | {SKAN_POSTBACK.APP_ID} | The "app-id" from the SKAdNetwork postback | Integer |
SKAdNetwork | {SKAN_POSTBACK. ATTRIBUTION_SIGNATURE} | The "attribution-signature" from the SKAdNetwork postback | String |
SKAdNetwork | {SKAN_POSTBACK. REDOWNLOAD} | The "redownload" from the SKAdNetwork postback Available with SKAdNetwork version 2.0 |
Integer |
SKAdNetwork | {SKAN_POSTBACK. SOURCE_APP_ID} | The "source-app-id" from the SKAdNetwork postback Available with SKAdNetwork version 2.0 |
Integer |
SKAdNetwork | {SKAN_POSTBACK. CONVERSION_VALUE} | The "conversion-value" from the SKAdNetwork postback Available with SKAdNetwork version 2.0 |
Integer |
SKAdNetwork | {ATTRIBUTION_IP} |
The IP of the SKAdNetwork postback |
String |
Singular | {SKADNETWORK_IS_VALID} |
If Singular was able to verify the install-signature of the postback (0 or 1) | Integer |
Singular | {ATTRIBUTION_COUNTRY} | Two-letter country code (e.g., US) of the SKAdNetwork postback, based on the IP E.g. US |
String |
Singular | {ATTRIBUTION_STATE} | The geolocated state/province of the SKAdNetwork postback, based on the IP E.g. California |
String |
Singular | {ATTRIBUTION_CITY} | The geolocated City of the SKAdNetwork postback, based on the IP E.g. San Francisco |
String |
Singular | {CONVERSION.PARTNER_ CONVERSION_NAME} | For supported conversion models and names, the event name supported by the partner, automatically mapped by Singular E.g., Partner Purchase Event |
String |
Singular | {CONVERSION.ADVERTISER_ CONVERSION_NAME} | The advertiser named conversion name. E.g., My Purchase Event |
String |
Singular | {CONVERSION.ADVERTISER_ CONVERSION_VALUE} | The advertiser defined conversion value for the conversion E.g., 5 |
String |
Singular | {CONVERSION.ADVERTISER_ CONVERSION_CURRENCY} | For supported revenue conversion models, the currency code of the conversion (typically the account currency) E.g. USD |
String |
Singular | {CONVERSION.ADVERTISER_ CONVERSION_MODEL_TYPE} | The name of the conversion model type the advertiser is using. E.g., Revenue |
String |
Singular | {CONVERSION.ADVERTISER_ CONVERSION_MODEL_NAME} | The advertiser configured name for the conversion model E.g., My IAP Revenue Model |
String |
Reference: Conversion Info API
Use conversion_info to retrieve Singular’s record of conversion model information about a specific advertiser's SKAdNetwork conversion-value.