Postback macros for ad networks

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 AppsFlyer. 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 AppsFlyer 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 AppsFlyer

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 AppsFlyer SDK

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

Derived by the AppsFlyer platform

Information derived by the AppsFlyer 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: AppsFlyer SDK embedded in the app or server-to-server API
    • AF: After processing by AppsFlyer
  • 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 AppsFlyer unique identifier recorded on conversion Yes  
attributed_touch_type SDK No Possible values Click, impression, TV, pre-installed, and so on 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  
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  

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, AppsFlyer 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
Was this article helpful?