Advanced Privacy guide & postback macros for ad networks

At a glance: Data sharing with partners when Advanced Privacy is enabled. Instructions for ad networks on setting up Advanced Privacy postbacks. Note! This article is not related to either SKAdNetwork postbacks nor is it intended for use by advertisers. 

Advanced Privacy for Ad Networks news

Updated March 22, 2021

The Advanced Privacy postback mechanism described in this article works when all of the following are true:

  • The user device is running iOS 14.5+ (General Availability)
  • Apple has begun enforcing ATT
  • Advanced Privacy setting is on

AdvancedPrivacy.png

This article discusses: 

Ad network Advanced Privacy data-sharing principles

Starting with the general availability of iOS 14.5+ and ATT enforcement by Apple, the AppsFlyer Aggregated Advanced Privacy Framework (AAP) framework provides advertisers with the ability to control the availability of user-level attribution data provided via the AppsFlyer platform. 

In the context of ad networks, the AAP framework is implemented using Advanced Privacy (AP). For ease of understanding, the terms Advanced Privacy and AP are used interchangeably in this article. 

AP doesn't impact the availability of aggregated data available to partners or ad networks. 

Attribution data include media source, campaign hierarchy, and other fields listed in restricted media source article. 

What data is affected by AP

When AP is on, user-level data for non-consenting users running iOS 14.5+ is not available via postbacks or other methods. For ad networks, this means that different types of postbacks are used depending on a user's ATT consent status and other factors. 

You can view the current AP setting, per app, in the AppsFlyer dashboard. Go to, Configuration > Integrated Partners > select your ad network > Integration tab. The default setting is on. 

APforPartners2.png

The postback types required for Advanced Privacy integration are:

  • Regular: Your existing integration template with AppsFlyer. Contains user-identifier and attribution-data macros.
  • Advanced Privacy: Template without user-identifier macros. If an AP postback is required and you haven't completed AP integration, no postback is sent. You can set up AP integration using our self-service Postback Management tool.

Note! If a user gives ATT consent in the apps of both the advertiser and the publisher ("dual consent"), regular postbacks are used.

Type of postback used 

The following table is applicable to the data of users running iOS 14.5+ (General Availability) with ATT enforcement by Apple. 

Note! If a user's iOS version is 14.4 or earlier, this table is not applicable and regular postbacks are sent. 

AP status

ATT status Postback type to attributed partner*  Unattributed postback partner*

Publisher app

Advertiser app

On

Authorized

Not authorized

Advanced Privacy

None

On

Not authorized

Authorized

Advanced Privacy

Regular. Attribution data is not available.

On

Authorized

Authorized

Regular. User-level with the following IDs: IDFA, IDFV, CUID, Click ID.

Regular. Attribution data is not available. 

On

Not authorized

Not authorized

Advanced Privacy

None

Off

N/A

N/A

Regular

Regular. Attribution data is not available.

Postback type used for iOS 14.5+

(*) Principles for data sharing with partners

For any given event, multiple ad network partners may be entitled to a postback. The postbacks sent are as follows:

  • Attributed partner: Ad network credited with the event
  • Unattributed partner: Integrated partner not credited with the event, when the In-app events postback > Sending option is set to All media sources including organic. If the advertiser app has ATT consent, the postback contains user IDs without attributed data. (This option is not supported by all ad networks.)

    InAppEventAll.png

Web campaigns

AP behaves differently when the ad network serves an ad on the web.

To indicate whether a click came from the web or from an app, you must send the af_media_type=web or af_media_type=app parameter in the click URL.

If you don't send af_media_type, the default is app.

ATT status Postback type to attributed partner* Postback type to unattributed partner*

Publisher app

Advertiser app

N/A

Not authorized

Advanced Privacy

None

N/A

Authorized

Regular. User-level with the following IDs: IDFA, IDFV, CUID, Click ID.

Regular. User-level IDs only.

Postback type used for iOS 14.5+ when AP is on

Integration

Update your click URLs and complete Advanced Privacy integration.

Click URL requirements

In many cases, depending on user ATT consent, IDFA will be unavailable in the publisher app, the advertiser app, or both. In these instances, AppsFlyer may perform attribution using Aggregated Advanced Privacy and probabilistic modeling.

[Best practice] To maximize your attributions, send all parameters listed.

  1. Append the following parameters to click URLs:
    Identifier Click parameter

    Example

    Campaign

    c

    US_20_30

    Campaign ID

    af_c_id

    12345

    Adset

    af_adset

    ADSET_1

    Adset ID

    af_adset_id

    56789

    Ad 

    af_ad

    creative_name

    Ad ID

    af_ad_id

    34567

    Site ID

    af_siteid

    abcdefgh12345678

    Subsite ID

    af_sub_siteid

    abcdefgh12345678

    Channel

    af_channel

    channel_name

    Ad type

    af_ad_type

    video

    iOS device model*

    af_model

    The device model. Values permitted:

    • iphone (all lower case)
    • ipad (all lower case)

    Operating system*

    af_os

    The operating system version

    * Some information may also be provided via the user agent. In this case, the value sent using the specific identifier takes precedence.


    Append campaign details to the click URL

    The example that follows shows how to add your campaign details to the click URL:

    https://app.appsflyer.com/id123456789?pid=YOUR_NETWORK_ID&c={CampaignName}&af_c_id={CampaignID}&af_adset={adset name}&af_adset_id={adset ID}&af_ad={ad name}&af_ad_id={ad ID}&af_ad_type={Ad type}&af_siteid={PublisherId}
  2. Add the following mandatory parameters to click URLs*:

     Caution

    If your click URL does not pass the mandatory parameters, you will not be credited with the majority of installs you drive.

    • IP 
    • User-agent 
    • Language

    * No action is required when sending a click using a simple HTTP referrer that redirects to AppsFlyer. 

    Use the extraction method described to append the parameters to the click URL when using either of the following methods: 

    • Redirect via in-app 
    • Server-to-server clicks (aka, S2S) 

    Parameter

    Extraction method

    Device language and locale

    af_lang

    NSString *language = [[NSLocale preferredLanguages] objectAtIndex:0];

    [Recommended] Provide the language and locale; for example, en-US.

    User-agent

    af_ua

    Extract the user-agent with the format:

    Mozilla%2F5.0+%28iPhone%3B+CPU+iPhone+OS+13_3_1+like+Mac+OS+X%29 
    +AppleWebKit%2F605.1.15+%28KHTML%2C+like+Gecko%29+Mobile%2F15E148
    • Do not extract the CFNetwork user-agent, extract the other one. 
    • The user-agent should be URL encoded.

    Device IP address

    af_ip

    Best option: If available, provide the device IP under the af_ip parameter.

    Next option: If available, AppsFlyer will use the IP in X-Forwarded-For.

    Mandatory parameters required for Advanced Privacy attribution


    Append parameters to the click URL

    To pass these mandatory parameters on the click attribution link, use this reference: 

    https://app.appsflyer.com/id123456789?pid=YOUR_NETWORK_ID&c={CampaignName}&af_c_id={CampaignID}&af_adset={adset name}&af_adset_id={adset ID}&af_ad={ad name}&af_ad_id={ad ID}&af_ad_type={Ad-type}&af_siteid={PublisherId}&af_ua={USER-AGENT}&af_lang={LANGUAGE}&af_ip={IP}

    Example

    GET https://app.appsflyer.com/id123456789?pid=YOUR_NETWORK_ID&c={CampaignName}&af_c_id={CampaignID}&af_adset={adset name}&af_adset_id={adset ID}&af_ad={ad name}&af_ad_id={ad ID}
    &af_ad_type={Ad type}&af_siteid={PublisherId}

    &af_ua=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%2012_1_4%20
    like%20Mac%20OS%20X%29%20AppleWebKit%

    2F605.1.15%20%28KHTML%2C%20like%20Gecko%29%20Mobile%2F16D57&af_lang=en-US&af_ip=11.11.1.11

    * Query parameters must be URL-encoded.

    Pass data on click URL headers

    To pass the fields on the click URL header, use this reference:

    GET https://app.appsflyer.com/id123456789?pid=YOUR_NETWORK_ID&c={CampaignName}&af_c_id={CampaignID}&af_adset={adset name}&af_adset_id={adset ID}&af_ad={ad name}&af_ad_id={ad ID}&af_ad_type={Ad type}&af_siteid={PublisherId}

    accept-language: en-US,en;q=0.

    User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X)

    AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148

    X-Forwarded-For: 11.11.1.11, 222.222.2.222

Advanced Privacy postback specification

To receive Advanced Privacy postbacks, you must set up an Advanced Privacy integration in addition to the regular postback integration. You can configure the Advanced Privacy postback yourself in the AppsFlyer dashboard.

Differences between the regular template and Advanced Privacy template

  • Postback time does not correlate with actual event times.
  • Timestamp macros:
    • For installs and in-app events, timestamps are rounded down to the hour in which they occurred. For example, 22:55:30 is reported as 22:00:00.
    • Are reported using the UTC time zone. Example timestamp: (2020-07-20 20:00:00)
  • The following parameters are not available in Advanced Privacy postbacks: Click ID, Customer User ID, AppsFlyer ID, IDFA, IDFV, device model, OS version, carrier.

Action required by the ad network to integrate:

  1. Set up your Advanced Privacy postback in the AppsFlyer dashboard. 
  2. Test Advanced Privacy integration.
Postback type
Install
In-app
Advanced Privacy postback endpoint [complete as required]

Postback macro (name)

Remarks Base parameters for all postbacks Optional parameters for in-app events  Optional parameters for rejected attribution
af_ad Creative name Yes    
af_ad_id 34567 Yes    
af_ad_type Like: banner, footer, video Yes    
af_adset ADSET_1 Yes    
af_adset_id 56789 Yes    
app_id - Yes    
app_name - Yes    
attributed_touch_hour

Rounded down to the nearest hour. 

Format see note (1)

Yes    
attributed_touch_type Such as: click, impression Yes    
blocked_reason Relates to validation rules/Protect360     Yes
blocked_reason_value Relates to validation rules/Protect360     Yes
blocked_sub_reason Relates to validation rules/Protect360     Yes
bundle_id As set by the advertiser Yes    
c Campaign name, like, US_20_30 Yes    
af_c_id Campaign ID, like, 12345 Yes    
af_channel Channel name Yes    
country_code ISO country code recorded on conversion Yes    
event_hour

Rounded down to the nearest hour. 

Format see note (1)

Yes    
event_name As reported by the app   Yes  
event_revenue Revenue amount in event currency   Yes  
event_revenue_
currency
Revenue currency code   Yes  
event_revenue_usd Revenue converted to USD   Yes  
install_hour

Rounded down to the nearest hour. 

Format: see note (1)

Yes    
is_first True if this is the first time this in-app event was triggered by a specific end-user   Yes  
is_primary

Use to deduplicate

Boolean: 0, 1

  Yes  
is_retargeting

Use to deduplicate 

Format: See note (2)

Yes    
is_reengagement

Format: See note (2)

  Yes  
is_reattribution

Use to deduplicate 

Format: See note (2)

Yes    
match_type Like: id_matching, probabilistic Yes    
event_id Name/ID of the corresponding event in the ad network platform   Yes  
platform Like: ios, Android Yes    
postback_id Unique postback ID Yes    
retargeting_
conversion_type
Such as: re-engagement, re-attribution Yes    
af_siteid abcdefgh12345678 Yes    
af_sub_siteid abcdefgh12345678 Yes    

Notes:

(1) Timestamp formats available:

  • [Default] String: YYYY-MM-DD HH:SS
  • Epoch time: 10-digit Unix timestamp 

(2) Boolean format available

  • [Default] Numeric: 0, 1 
  • String: false, true
Advanced Privacy attribution macros available

Setting up your Advanced Privacy postback

Set up your AP postback using the Postback management option in the AppsFlyer dashboard.

Prerequisites:

  • You must have an active integration with AppsFlyer to manage your Advanced Privacy postback. Contact integrations@appsflyer.com to create an integration.
  • AppsFlyerAdmin_us-en.png Postback management is performed by the account admin; team members do not have access.

To set up the postback:

  1. Click the top-right drop-down menu > Postback management.
  2. Select the postback type: Advanced Privacy. 
  3. Activate the builder.

    postback-management-enter-endpoint_en-us.png

  4. Enter the endpoint address: The endpoint URL to which AppsFlyer sends postbacks. Enter the relevant URLs for installs and/or in-app events.
  5. Enter the parameters to be included in the postbacks:
    • Parameter name: AppsFlyer parameter screen name
    • Your receiving parameter: the respective receiving parameter on your side
    • Parameter value (available for some parameters): choose the value format. For example, for Boolean values, choose whether to receive them as "true"/"false", or 1/0.
    • Install: check the box to include the parameter in the install postback.
    • In-app event: check the box to include the parameter in the in-app event postback.

     

    postback-management-parameters_en-us.pngFull list of SKAdNetwork postback macrosFull list of Advanced Privacy postback macros

  6. [Optional] Add custom parameters that are not provided by AppsFlyer:

    postback-management-custom-parameters_en-us.png

  7. Check the final postback template preview to make sure everything is correct.

    postback-management-template_en-us.png

  8. Click Save. Note that when you save the postback, the changes take effect immediately.

In the case of any issues, reach out to integrations@appsflyer.com.

Additional information

AP for analytics partners

Postbacks are sent to analytics partners as follows:

  • AP off: User-level postback without restriction.
  • AP on: According to user source and ATT status as detailed in this table; 

User source

ATT status Postback type to analytics partner

Publisher app

 Advertiser app

Non-organic 


 


 

Authorized

Authorized

Regular

Not authorized

Authorized

None

Any value

Not authorized

None

Organic or web

N/A

Authorized

Regular

Organic or web

N/A

Not authorized

None
Analytics partner postback type according to ATT status and user source

AP vs. SKAdNetwork

SKAdNetwork is an attribution technology provided by Apple for iOS devices. Advanced Privacy is part of the AppsFlyer Aggregated Advanced Privacy (AAP) framework and relates to attribution performed by AppsFlyer. AAP provides advertisers the ability to control the availability of user-level attribution data via the AppsFlyer platform. Typically ad networks support both AP and SKAdNewtork integration. 

Was this article helpful?