Postbacks: SKAdNetwork integration guide for ad networks

 At a glance: The AppsFlyer solution for SKAdNetwork, provides ad networks with postbacks containing decoded conversion value data. 

Postbacks to AppsFlyer

Once you receive the postback from the device you are requested to send it to AppsFlyer using one of cthe methods listed below:

  • POST
  • HTTP 307 redirect

Upon postback receipt AppsFlyer will do the following:

  • Validate and ensures that the postback is unique.
  • Decode the conversion value and generate attribution install and in-app records.
  • Sends decoded postbacks to the ad network.
  • Makes attribution data available via dashboards and reports to the advertiser.

POST

Requirements:

  1. Postbacks must include the mandatory parameters and other relevant parameters like campaign ID, campaign name, timestamp, and IP address
  2. Send the postback to AppsFlyer
SKAdNetwork postback to AppsFlyer
Endpoint

https://skadpostbacks.appsflyer.com/api/postbacks

HTTP method POST
Accepted content types application/json
Return codes

200 OK: Postback received having valid format and signature

400: Bad request: Malformed JSON, empty, JSON, invalid signature

SKAdNetwork postback JSON parameters

Parameter

Format

Description

Source

Mandatory for SKAdNetwork version 1.0

Mandatory for SKAdNetwork version 2.0

ip String

The IP address of the device sending the postback.

iPv4 and IPv6 addresses permitted.

Example: "ip":"198.51.100.1"

Ad network No No
version String

SKAdNetwork version

Example: "version":"2.0"

SKAdNetwork No Yes
ad-network-id String

Ad network ID

Example: "ad-network-id":"1232"

SKAdNetwork Yes Yes
campaign-id Integer

SKAdNetwork campaign ID

Example: "campaign-id":23

SKAdNetwork Yes Yes
ad-network-campaign-id String

If you are integrated with AppsFlyer for advertiser spend (cost) via API, you must enrich the postback with the ad-network-campaign-id. Without it, AppsFlyer can't display your cost data in the SKAdNetwork dashboard.

Ad network campaign ID associated with the SKAdNetwork campaign ID. This is the ID that is used in postbacks and dashboards.

Ad network No No
ad-network-campaign-name String Ad network campaign name associated with the ad network campaign ID. This is the name that displays in dashboards. Ad network No No
transaction-id String

SKAdNetwork postback transaction ID

SKAdNetwork  Yes (1) Yes (1)
app-id Integer Target app ID SKAdNetwork  Yes Yes
attribution-signature String Attribution signature SKAdNetwork  Yes (1) Yes (1)
redownload Boolean When redownload = true, it means the user downloaded the app from the app store again. SKAdNetwork  No Yes
source-app-id Integer

Source App ID (publisher)

SKAdNetwork  No Yes
conversion-value Integer Conversion value. Value set by the AppsFlyer SDK according to the advertiser settings. SKAdNetwork  No Yes
timestamp Integer

Time the ad network received the SKAdNetwork. 10-digit UNIX timestamp.

Example:

August 4, 2020, 07:25 UTC translates to "timestamp": "1596525944"

Ad network No No
dry-run Boolean

Test postbacks

If true, indicates that it is a test message and must not be recorded nor attributed. These messages are discarded. 

 

Ad network No No

Note:

(1) When using dry-run=true, transaction-id & attribution-signature values are not validated.

Curl example postback version 2.0

curl --location --request POST 'https://skadpostbacks.appsflyer.com/api/postbacks' \
--header 'Content-type: application/json' \
--data-raw '{
    "version":"2.0",
    "app-id": 123456789,
    "ip": "1.1.1.1",
    "ad-network-campaign-name": "skadnetwork_facebook_campaign",
    "source-app-id": 888707074,
    "ad-network-id": "example123.skadnetwork",
    "transaction-id": "868eb3d91-15f5-44ee-9267-25c7655c20b6",
    "redownload": false,
    "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
    "timestamp": "1597156649200",
    "ad-network-campaign-id": "222222",
    "conversion-value": 23,
    "campaign-id": 99
}'

POST test procedure

Test the integration by setting dry-run=true in the JSON using the same format as described above. 

When using dry-run=true, transaction-id & attribution-signature values are not validated.

Response Codes

  • 200 OK: Postback received having valid format and signature
  • 400: Bad request: Malformed JSON, empty, JSON, invalid signature, an error message is contained in the JSON that returns. 

Example

curl --location --request POST 'https://skadpostbacks.appsflyer.com/api/postbacks' \
--header 'Content-type: application/json' \
--data-raw '{    
    "dry-run": true, 
    "version":"2.0",
    "app-id": 123456789,
    "ip": "1.1.1.1",
    "ad-network-campaign-name": "skadnetwork_facebook_campaign",
    "source-app-id": 888707074,
    "ad-network-id": "example123.skadnetwork",
    "transaction-id": "868eb3d91-15f5-44ee-9267-25c7655c20b6",
    "redownload": false,
    "attribution-signature": "MDYCGQCsQ4y8d4BlYU9b8Qb9BPWPi+ixk/OiRysCGQDZZ8fpJnuqs9my8iSQVbJO/oU1AXUROYU=",
    "timestamp": "1597156649200",
    "ad-network-campaign-id": "222222",
    "conversion-value": 23,
    "campaign-id": 99
}'

HTTP 307 redirect

This method requires very little coding or development by the ad network. 

Principles:

  • Ad networks receive the postback from the iOS device.
  • If AppsFlyer is the app attribution provider, the ad network returns an HTTP 307 response to the iOS device designating https://skadredirect.appsflyer.com/api/redirects as the redirect endpoint. 
  • The device receives the redirect HTTP 307 message and sends the postback to AppsFlyer.
  • AppsFlyer receives and processes the postback.
  • Note: Campaign ID mapping between you and AppsFlyer must be handled separately for the redirect flow to work. Contact your AppsFlyer partner development manager for more details.

Postbacks from AppsFlyer

  • Having decoded and attributed the SKAdNetwork postback, AppsFlyer sends the ad network install and in-app event postbacks, to enable networks to optimize their campaigns accordingly.
  • You must define the postback endpoint and template. To do so, reach out to your partner development manager.
  • The same install or event can be attributed by more than one AppsFlyer attribution solution. Use the attribution_source parameter to differentiate between the solutions. 

Postback format 

Key

Description

Format and example

site_id

The app publishing the ad (source app ID)

String: 876534

install_time

Estimated by AppsFlyer based on the updateConversion window. Provided as a 10-digit UNIX timestamp

  • String: 1596119460 
  • Translates to July 30, 2020, 14:31 UTC.

event_time

Estimated by AppsFlyer based on the updateConversion window. Provided as a 10-digit UNIX timestamp

  • String: 1596119460 
  • Translates to July 30, 2020, 14:31 UTC

skad_ad_network_time

Time the postback was received by the ad network from the iOS device. Reported by the ad network. Provided as a 10-digit UNIX timestamp

  • String: 1596119460 
  • Translates to July 30, 2020, 14:31 UTC




skad_af_received_time

Time AppsFlyer received the postback from the ad network. Provided as a 10-digit UNIX timestamp

 

  • String: 1596119460 
  • Translates to July 30, 2020, 14:31 UTC

event_name

Event name 

  • af_purchase
  • af_login
  • af_skad_revenue
  • or as set by the advertiser 

String: af_purchase, abc123

 

revenue

Revenue amount using the specified currency code

Number: 5, 20, 0.4

currency

Currency code being the app-specific currency set by the advertiser

String: EUR, USD, ZAR

attribution_source

The source of the attribution data:

SKAdNetwork: skadnetwork

String: skadnetwork

app_id

App ID (advertiser app)

String: ID123456790

country

Install country determined using IP address sent by the ad network

String: US, UK, ZA 

campaign

Campaign name populated using ad-network-campaign-name sent in the postback from the ad network

String: UA_US_23+

campaign_id

Ad network Campaign ID populated using ad-network-campaign-id sent in the postback from the ad network

String: 3456745

redownload

Possible values: true, false

When redownload = true, it means the user downloaded the app from the app store again

Boolean: true, false

SKAdNetwork postback from Appsflyer to the ad network

Example in-app SKAdNetwork postback

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

Postback release notes

SKAdNetwork postback release notes
Date  Notes
2020-09-22
  • The format of redownload is changed from integer to boolean. True means the user redownloaded and reinstalled the app.
  • This change is made to align with the Apple postback specification.
Was this article helpful?