Skip to main content

Postback macros for ad networks

John Smith

At a glance: As an ad network, you can define the content and endpoints of postbacks sent to you as part of your integration with ZendeskConnect. Postbacks relate to app user engagement like installs, in-app events, re-engagements, and so on.

Related integrated partner postback guides:

Postbacks for ad networks

  • Postback configuration: To request changes to your postback settings, contact integrations@appsflyer.com or your ZendeskConnect partner development manager. 
  • Postback types: Postbacks are available for install and in-app events and blocked install and in-app events (due to fraud identified by Protect360 or in violation of targeting validation rules).
Postback data sources
Source Description
Attribution link parameters

Parameters provided by the partner on click and impression URLs

Example: click ID parameter on the attribution link - "&click_id=CLICK_ID"
Partner IDs in ZendeskConnect

Unique IDs provided to the advertiser by the partner

Examples: app ID, account ID, user ID, network ID
SDK derived information

Information extracted from the device by the ZendeskConnect SDK

Example: iOS device IDs can be extracted by using "&IDFA=(idfa)" on the postback
Derived by the ZendeskConnect platform

Information derived by the ZendeskConnect platform. 
Protect360 and validation rules Information about installs identified as fraud and installs violating campaign targeting rules, and their associated in-app events

Postback macros

When included in a postback, macros are replaced with the user-relevant data. For example, to get the IP address of the user installing the app, include country_code=(ip) in the postback structure. Supported macros supported are listed in the following table:

The columns in the table that follows have the following meaning:

  • Source: Where the data originates from.
    • Link: Attribution links
    • SDK: ZendeskConnect SDK embedded in the app or server-to-server API
    • AF: After processing by ZendeskConnect
  • Send all: If yes, you can receive the data of installs and events attributed to other networks or organic. (Means not attributed to you). 
  • [Base] Macros for all postbacks: Macros relevant to install, in-app event, and rejected event postbacks
  • [Optional] for in-app events and rejected events as indicated in the column (rejected, in-app)
Macros—installs, in-app events, and rejected events
Postback macro (name) Source Send all Description [Base] Macros for all postbacks [Optional] In-app and rejected events
advertising_id SDK Yes User-resettable device ID, AKA GAID. Also available as: (sha1-advertiserId) Yes  
app_name SDK Yes App name set by the advertiser Yes  
appsflyer_id SDK Yes ZendeskConnect unique identifier recorded upon conversion Yes  
attributed_touch_type SDK No Possible values: click, impression, TV, pre-install Yes  
blocked_reason AF No Fraud/validation rules reason No Rejected
blocked_reason_value AF No Fraud/validation rules reason value (like site ID) No Rejected
blocked_sub_reason AF No Fraud/validation rules sub-reason No Rejected
bundle_id SDK Yes iOS: Identification to match either a single app or a group of apps in iOS (See Apple developer bundle ID) Android: The app name Yes  
country_code AF Yes Country Code using ISO 3166 (alpha-2) Example: US, CN. Yes  
event_name SDK Yes Name allocated to an event No In-app
event_revenue_USD AF Yes Event value in USD No In-app
event_revenue SDK Yes Event value reported by SDK using event_revenue_currency or currency selected by you. No In-app
event_revenue
_currency		 SDK Yes The event revenue currency code reported in the event or the currency selected by you No In-app
event_time SDK Yes Event time No In-app
event_value SDK Yes in-app event includes attributes with values, which can be sent entirely on the postback in JSON format. URL encoded using the (encode) macro. No In-app
idfa SDK Yes User resettable advertising ID found on iOS devices Also available as: (sha1-idfa) Yes  
idfv SDK Yes Unique identifier per user per vendor on IOS devices Yes  
install_time SDK Yes Install timestamp Yes  
install_unix_ts SDK Yes Install timestamp in unix format Yes  
is_attributed AF Yes A flag marking if the install or event is attributed to this media source Yes  
is_lat SDK Yes Limit ad tracking (LAT): iOS: Starting iOS 14 LAT is deprecated by Apple. Determine user privacy status using ATT. In this case disregard is_lat. Before iOS 14, if true, IDFA is not available and is set to 0. Android: When true, the user has opted-out of interest-based ads. This does not prevent the collection of GAID. Yes  
is_primary_attribution AF Yes

If false, see is_retargeting.

 No In-app
is_retargeting Link No

Use in conjunction with is_primary_attribution. Learn more about double attribution of retargeting events.

If true (1), the event is reported as part of a retargeting campaign and the media source is the retargeting media source.

If false (0) and is_primary_attribution is false, the event is part of a retargeting campaign but the media source referenced is the user attribution media source

 

 No  
language SDK Yes Language (locale) reported by the device and set by the device OS. Yes  
oaid SDK Yes User-resettable ID on some Android devices usually as an alternative to GAID Yes  
partner_event_id AF Yes Name/ID of the corresponding event in the partner's platform No In-app
platform SDK Yes Device platform: iOS, Android, or Windows Mobile Yes  
retargeting_
conversion_type		 AF No A flag marking if this is a re-attribution or re-engagement Retargeting only  
app_version SDK Yes App version name set by the developer in the app code Yes  
app_id SDK Yes The app ID as reported by the app  Yes  
att-0-1 SDK Yes

Possible values:

  • 1: The ATT status is authorized or af_authorized.
  • 0: Any other ATT status. 
 Yes  
att-status SDK Yes

The ATT status reported by iOS. Like authorized, not_determined. 

In some cases there is no value and "" is returned. 

 Yes  
af_ad LINK No

Ad Name (see more) provided by the advertiser/publisher

 Yes Yes
af_ad_id LINK No

Provided by the advertiser/publisher

 Yes Yes
af_adset Link No
  • Provided by the advertiser/publisher.
  • Adset is an intermediate level in the hierarchy between Campaign and Ad. See more
Yes Yes
af_adset_id Link No Provided by the advertiser/publisher Yes Yes
c Link No Provided by the advertiser/publisher. Campaign names that exceed 100 characters in length are displayed on the dashboard as "c_name_exceeded_max_length" Yes Yes
af_c_id Link No Provided by the advertiser/publisher Yes Yes
af_siteid Link No
  • Unique ID that identifies the publisher that displays the ad. Learn more
Yes Yes
af_subsite_id Link No
  • Ad sub-network/Publisher ID. 
  • If in addition to the main publisher (site ID), there is a sub-publisher, or you want to include additional info, such as ad type/placement within the app, like banner, interstitial, video, etc. use af_sub_siteid. For example: af_sub_siteid =ABCD_4567
 Yes Yes
af_ad_type Link No

Use the following naming convention:

  • text: an ad unit containing only text, for example a search result
  • banner: a basic format that appears at the top or bottom of the device screen
  • interstitial: a full-page ad that appears during breaks in the current experience
  • video: a standard video, that is non-rewarded
  • rewarded_video: an ad unit offering in-app rewards in exchange for watching a video
  • playable: an ad unit containing an interactive preview of the app experience
  • sponsored_content: a link included in a piece of sponsored content, like an advertorial article
  • audio: an audio ad
Yes Yes
imei SDK Yes

A unique number used to identify mobile phones

 Yes  

In-app event only macros

The examples that follow relate to in-app event postbacks available to partners.

Example

Event postback template "&event=(event)&json=(encode)" was translated to the following postback for a specific af_purchase event:

&event=af_purchase&json=%7B%22af_quantity%22%3A1%2C%22
af_revenue%22%3A%2212000%22%2C%22af_currency%22%3A%
22USD%22%2C%22af_content_id%22%3A%221107%22%2C%22
af_content_type%22%3A%22default_type%22%7D%0A

The decoded JSON value of this postback is

{"af_quantity":1,"af_revenue":"12000","af_currency":"USD","af_content_id":"1107","af_content_type":"default_type"}


Encoded values

Postbacks may contain irregular characters, which are not alpha-numerical. To transfer these values correctly via postbacks, ZendeskConnect URL-encodes non-alpha-numerical values.

To decode or encode a postback use an encoding web service. 

Sample postbacks

General install postback examples

Android iOS 
http://YourCompanyDomain.com?site_id=(publisher_id)
&advertising_id=(advertiser_id)&android_id=(android_id)
&install_time=(install_unix_ts)

General in-app event postback examples

Android iOS 
http://YourCompanyDomain.com?site_id=(publisher_id)&
device_ip=(ip)&advertising_id=(advertiserId)&android_id=(android_id)&
install_time=(install_unix_ts)&event_name=(event_name)&currency=(currency)&
json=(event_value)

 In-app event postback example

Event Parameters:

  • Event Name: af_revenue
  • Event Revenue: 120.00
  • Event Currency: USD
  • Event Value: {"af_quantity":1,"af_revenue":"120","af_currency":"USD","af_content_id":"1107","af_content_type":"default_type"}

Postback:

http://YourCompanyDomain.com?clickid=8594845&site_id=click123&device_ip=
38.166.144.142&advertising_id=121sxxxx-xxxx-xxxx-xxxx-52454bd7500b&
android_id=9aaeecc4455xxxxx&;install_time=1451923560&event_name=af_purchase&
currency=USD&revenue=120.00&json=%7B%22af_quantity%22%3A1%2C%22 />af_revenue
%22%3A%22120.10%22%2C%22af_currency%22%3A%22USD%22%2C%22af_content_id
%22%3A%221107%22%2C%22af_content_type%22%3A%22default_type%22%7D%0A

Comments

0 comments

Article is closed for comments.

Powered by Zendesk