Integrating with Singular SKAdNetwork - FAQ for Partners

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.

IDFA_307d.png

Data flow diagram for Singular's Secure SKAN

What is involved in integrating Singular's SKAdNetwork solution?

Integrating with Singular's SKAdNetwork solution is a separate process from the normal attribution integration with Singular. Having a working attribution integration with Singular is a prerequisite before following the steps below to integrate with 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.

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. Handling the conversion event postback

After you send Singular an SKAdNetwork postback using one of the methods above, 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.

Note: The SKAdNetwork conversion postback is separate (and needs to be configured separately) from any attribution postbacks or event postbacks you may be receiving through an attribution integration with Singular.

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.

4. Handling the Campaign ID

If you use the Secure SKAN method to report SKAdNetwork postbacks to Singular, you can use Singular’s skan_campaign_info API to send Singular information about SKAdNetwork campaign IDs and their meanings, which will provide valuable campaign performance information for the advertiser.

I want to integrate with Singular's SKAdNetwork solution. Where do I start?

  1. Gather requirements: Review What is a Singular SKAdNetwork Integration? to understand the integration details and options available.
  2. Fill out the integration form for Singular's SKAdNetwork solution.
  3. 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.
  4. 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

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
E.g.136.25.2.194

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

(Coming Soon) Reference: Conversion Model API

Get_skan_conversion_model

Use get_skan_conversion_model to retrieve Singular’s record of conversion model information about a specific advertiser's SKAdNetwork conversion-value.

 

Was this article helpful?