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

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+
• Advanced Privacy is on

This article discusses: 

• The impact of Advanced Privacy data sharing on partners
• Click URL requirements in order to be eligible for attribution
• Setting up your Advanced Privacy postbacks in the ZendeskConnect dashboard
• The difference between Advanced Privacy and SKAdNetwork.

Ad network Advanced Privacy data-sharing principles

Starting iOS 14.5+ the ZendeskConnect Aggregated Advanced Privacy Framework (AAP) provides advertisers with the ability to control the availability of user-level attribution data provided via the ZendeskConnect 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.  

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 reporting methods including Protect360 fraud-related reports.

In the context of postbacks it 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 ZendeskConnect dashboard. Go to, Configuration > Integrated Partners > select your ad network > Integration tab. The default setting is on. 

The postback types required for Advanced Privacy integration are:

• Regular: Your existing integration template with ZendeskConnect. 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 sent to both the attributed and non-attributed ad networks.  

Type of postback used 

The following table is applicable to the data of users running iOS 14.5+.

Note! If the iOS version is 14.4 or before, the table that follows isn't applicable. It means that postbacks using the regular template are sent to both the attributed and non-attributed ad network. 

Postback type for iOS 14.5+

AP status	ATT status		Postback template type to attributed partner* supporting AP	Postback template type to attributed partner* not-supporting AP	Unattributed postback partner*
	Publisher app	Advertiser app
On	Authorized	Not authorized	AP template	No postback	None
On	Not authorized	Authorized	AP template	No postback	Regular template. Attribution fields aren't available.*
On	Authorized	Authorized	Regular template. This includes available IDs like: IDFA, IDFV, CUID, Click ID and attribution fields.	Regular template. This includes available IDs like: IDFA, IDFV, CUID, Click ID and attribution fields.	Regular template including available IDs. Attribution fields aren't available.*
On	Not authorized	Not authorized	AP template	No postback	None
Off	Not considered	Not considered	Regular	Regular	Regular template. Attribution fields aren't available.*

(*) 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.)

  

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.

Postback type used for iOS 14.5+ when AP is on

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.

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, ZendeskConnect 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 

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

   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) 

    Parameters for Advanced Privacy attribution

   Parameter	Mandatory	Extraction method
   Device language and locale af_lang	No	NSString *language = [[NSLocale preferredLanguages] objectAtIndex:0]; [Recommended] Provide the language and locale; for example, en-US.
   User-agent af_ua	Yes	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	Yes	Best option: If available, provide the device IP under the af_ip parameter. Next option: If available, ZendeskConnect will use the IP in X-Forwarded-For.

   
   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 ZendeskConnect dashboard.

Differences between the regular template and Advanced Privacy template

• Postbacks are sent in hourly batches.
  • The batches include all event types.
  • The batches include both attribution and rejection postbacks.
  • 0.001% of postbacks may be sent in later batches, with possible delays of up to 24 hours.
• 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, ZendeskConnect 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 ZendeskConnect dashboard. 
2. Test Advanced Privacy integration.

Postback type

Install

In-app

Advanced Privacy attribution macros available

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:MM:SS Epoch time: 10-digit Unix timestamp  (2) Boolean format available [Default] Numeric: 0, 1  String: false, true

Setting up your Advanced Privacy postback

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

Prerequisites:

• You must have an active integration with ZendeskConnect to manage your Advanced Privacy postback. Contact [e-mail] to create an integration.
• 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.
   

   

4. Enter the endpoint address: The endpoint URL to which ZendeskConnect 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: ZendeskConnect 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.

   

   Complete list of Advanced Privacy postback macros.

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

   

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

   

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

In the case of any issues, reach out to [e-mail].

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; 

Analytics partner postback type according to ATT status and user source

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

AP vs. SKAdNetwork

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