SKAN integration guide for ad networks

Using this method, ad networks forward each postback received from the device to AppsFlyer.

The ad network:

• Receives the postback from the iOS device.
• [Mandatory] Enriches the postback with:
  • Ad network campaign ID and campaign name.
  • IP address received from the device, required mainly for geo resolution purposes. 
  • The timestamp of the postback sent from the iOS device.
• [Optional] Enriches the postback with:
  • Adset ID and name
  • Ad ID and name
  • Ad network name
  • Country code
  • Source app ID
  • Creative
  • Channel
• Sends the postback to AppsFlyer
• Note! Before sending the postback to AppsFlyer, validate the Apple attribution signature using the content of the outgoing postback to ensure that you didn't inadvertently corrupt the data.

SKAN enriched postback protocol

SKAN enriched postback JSON parameters

Curl example—enriched SKAN 3 postback

curl --location --request POST 'https://skadpostbacks.appsflyer.com/api/postbacks?app_id=id888707074' \
  --header 'Content-type: application/json' \
  --data-raw '{
      "version":"3.0",
      "app-id": 888707086,
      "ip": "192.0.2.0",
      "ad-network-campaign-name": "skadnetwork_abc_campaign",
      "source-app-id": 888707074,
      "ad-network-id": "abcabcabc.skadnetwork",
      "transaction-id": "68eb3d91-15f5-44ee-9267-25c7655c20b6",
      "redownload": false,
      "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
      "timestamp": "1596525944",
      "ad-network-campaign-id": "222222",
      "conversion-value": 63,
      "campaign-id": 99
  }'

Curl example—enriched SKAN 4 postback with fine conversion values

curl --location --request POST 'https://skadpostbacks.appsflyer.com/api/postbacks?app_id=id888707074' \
  --header 'Content-type: application/json' \
  --data-raw '{
      "version": "4.0"
      "ad-network-id": "example123.skadnetwork",
      "ad-network-campaign-name": "skadnetwork_abc_campaign",
      "ad-network-campaign-id": "222222",
      "source-identifer": "5239",
      "app-id": 525463029,
      "transaction-id": "6aafb7a5-0170-41b5-bbe4-fe71dedf1e30",
      "redownload": false,
      "source-app-id": 1234567891,
      "fidelity-type": 1, 
      "did-win": true,
      "conversion-value": 63
      "postback-sequence-index": 0
      "attribution-signature": "MEUCIGRmSMrqedNu6uaHyhVcifs118R5z/AB6cvRaKrRRHWRAiEAv96ne3dKQ5kJpbsfk4eYiePmrZUU6sQmo+7zfP/1Bxo="
  }'

Curl example—enriched SKAN 4 postback with coarse conversion values

curl --location --request POST 'https://skadpostbacks.appsflyer.com/api/postbacks?app_id=id888707074' \
  --header 'Content-type: application/json' \
  --data-raw '{
      "version": "4.0"
      "ad-network-id": "example123.skadnetwork",
      "ad-network-campaign-name": "skadnetwork_abc_campaign",
      "ad-network-campaign-id": "222222",
      "source-identifer": "39",
      "app-id": 525463029,
      "transaction-id": "6aafb7a5-0170-41b5-bbe4-fe71dedf1e31",
      "redownload": false,
      "source-app-id": 1234567891,
      "fidelity-type": 1, 
      "did-win": true,
      "coarse-conversion-value": "high"
      "postback-sequence-index": 0
      "attribution-signature": "MEUCIQD4rX6eh38qEhuUKHdap345UbmlzA7KEZ1bhWZuYM8MJwIgMnyiiZe6heabDkGwOaKBYrUXQhKtF3P/ERHqkR/XpuA="
  }'

Using this method, the ad network responds to the device with an HTTP redirect command (307), requesting the device to send the postback directly to AppsFlyer. 

The redirect method has the following advantages:

• Increased advertiser trust: The MMP acts on behalf of an advertiser. By providing AppsFlyer access to the postback firsthand, advertisers are confident that postbacks are not manipulated in transit.
  
• No processing required by the ad network: Ad networks respond with the redirect command (to the device), thus eliminating the need to process postbacks. In comparison, the enrich and forward method requires that ad networks consume the postback, enrich it with additional parameters, and finally forward it to AppsFlyer.

Implementation

1. Configure your server to respond with an HTTP 307 response redirecting the postback to https://skadnetworkredirect.appsflyer.com/api/redirects
2. Append query params that contain campaign details using the query params listed in the table that follows. Regard the sending of your campaign details as mandatory. Campaign details enable us to enrich SKAN data with cost and other campaign data and enable advertisers to effectively optimize campaigns.

Example redirect URL

https://skadnetworkredirect.appsflyer.com/api/redirects?
  &ad-network-campaign-id=243232&ad-network-campaign-name=yarg_campaign_name
  &ad-network-adset-name=dsdsa&creative=examplecreative&channel=channelexample

Query params for campaign details (not mandatory)

• For each postback sent from the ad network to AppsFlyer, AppsFlyer sends:
  • One install postback. Redownloads are signaled by the redownload parameter. 
  • Zero to several in-app event postbacks. The exact number depends on the translation of the conversion value. See simulated postbacks.
• When you consume postbacks, the same install or event can be attributed by more than one AppsFlyer attribution solution. Use the attribution_source parameter to differentiate between postback types. 

Example of an install SKAN postback sent by AppsFlyer

http://YourCompanyDomain.com/event?site_id=(publisher-id)&install_time=(timestamp)
  &skan_ad_network_time=(timestamp)
  &skan_af_received_time=(timestamp)
  &attribution_source=skadnetwork
  &app_id=(id123456789)&country=(ZA)&campaign=(campaign-name)
  &campaign_id=(campaign-id)&SKAN_ambiguous_event=(boolean)
&redownload=(boolean)
&af_SKAN_nonce=(uuid)

Example of an in-app SKAN postback sent by AppsFlyer

http://YourCompanyDomain.com/event?site_id=(publisher-id)&install_time=(timestamp)
  &skan_ad_network_time=(timestamp)
  &skan_af_received_time=(timestamp)&revenue=(value)
  &currency=(code)&event_name=(event-name)&attribution_source=skadnetwork
  &app_id=(id123456789)&country=(ZA)&campaign=(campaign-name)
  &campaign_id=(campaign-id)&SKAN_ambiguous_event=(boolean)
&redownload=(boolean)
&af_SKAN_nonce=(uuid)

Using this method, the ad network sends AppsFlyer actual SKAN postbacks from live apps. 

Testing integration

Test criteria

• Using this method, the ad network sends AppsFlyer preprepared postbacks to AppsFlyer test apps, as detailed in the table below. AppsFlyer replies with decoded postbacks to the ad network.
• Each test app has a different conversion value mapping, as detailed in the table.

Integration steps

Test criteria