Push APIs - Installation and Conversion Notification APIs

push-api-1-1.svg

Introduction

You can sync your attribution and marketing analytics data with your internal data platforms using Push API.

Push API enables advertisers to receive raw data messages via an HTTP request from AppsFlyer to any endpoint. A push API message can be sent upon every successful installation, in-app event or retargeting conversion, whether organic or not.

Messages are sent in near real-time, meaning that usually they are sent within a few seconds of the performed action, but may take up to two minutes.

The data is sent, by default, via an http POST or GET method and is JSON formatted. 

For the complete list of fields and message examples click here.

For field descriptions please read this.

Who Should Use Push API?

  1. Advertisers who need accurate attribution data sent to their servers in near real time 
    Combine your users' data with detailed AppsFlyer's attribution data as it happens, especially for analytics and segmentation purposes. [If you base your app's flow on the attribution data in real time, i.e. within 5 seconds of first app open, it is better to use AppsFlyer's conversion data API instead]

  2. Advertisers with complex data bases 
    If you need your data to be sent to different data bases in your system to collect install/in-app event/organic/non-organic data, Push API can do this with a simple 2 minute configuration saving you precious developing resources.

  3. Advertisers working with external data collection platforms
    With Push API you can send any install or event data to external systems by simply supplying their endpoint URL

 Note

The Push API is an AppsFlyer premium feature, which can be purchased as part of the API Access package. The package is available for free to advanced account tiers.
Please contact your CSM or AppsFlyer's support if you require more details. 

Push API Configuration

To configure your push API preferences follow the following steps:

1. On the dashboard, from the left hand menu under Integration select API Access

api_access_link.png

2. Scroll down to the Push API section and click Add Postback.

3. Choose the data you are interested to send. 
You can configure from 1 to 4 different postbacks for organic and non-organic installs and in-app events. If you also have retargeting traffic, you can configure up to 6 different postbacks.  

push_api.png

 Note

Push API only supports the use of port 80 and 443.

4. Enter the endpoint's URL to receive these postbacks.

5. Click Save.

After you save the changes, upon every conversion the data is sent to your endpoint's URL in the format provided in this document.

 Note

Additional fields may be added to the JSON structure from time to time without prior notice. Please Follow this article to get informed of any API changes.

Currently API key parameters are not supported as part of the push API.

 Warning

If the receiving client fails to collect the push message correctly it can't be resent. In case your client has some down time and loses push messages, you can always fill out the gaps using pull API.

IP Whitelisting

We recommend to whitelist AppsFlyer's IPs in your internal networks / platforms in order to successfully receive the Push API calls from AppsFlyer.

Visit the following link for the updated list of AppsFlyer's IPs.

TLS Support 

AppsFlyer's Push API supports the following TLS versions
  • 1.0
  • 1.1
  • TLS v1.0 
Handshake fails if the target endpoint supports only TLS v1.2 (ensure your endpoints support the earlier versions too).

Push API Structure

The Push API supports in-app events data in addition to installation data, both for organic and non-organic installs. It also sends retargeting campaign data, showing re-attributions and re-engagements.

Supported Fields

The table below shows all the available fields via Push API for organic or non-organic events.

Y - the field exists with a real or "null" value

N - the field doesn't exist or has a "null" value 

Field Non-Organic Install FB Install TW Install Organic Install Non-Organic In-App FB In-App TW In-App Organic In-App
attributed_touch_type Y Y Y N Y Y Y N
attributed_touch_time Y Y Y N Y Y Y N
event_type Y Y Y Y Y Y Y Y
attribution_type
(Organic or Regular)
Y Y Y Y Y Y Y Y
click_time Y Y Y Y Y Y Y Y
download_time Y Y Y Y Y Y Y Y
install_time Y Y Y Y Y Y Y Y
media_source Y Y Y Y Y Y Y Y
agency Y Y Y Y Y Y Y Y
af_channel Y Y Y N Y Y Y N
af_keywords Y Y Y  iOS: Y
And: N
Y Y Y N
campaign Y Y Y Y Y Y Y Y
af_c_id Y Y Y N Y Y Y N
af_adset Y Y Y N Y Y Y N
af_adset_id Y Y Y N Y Y Y N
af_ad Y Y Y N Y Y Y N
af_ad_id Y Y Y N Y Y Y N
fb_campaign_name Y Y Y Y Y Y Y Y
fb_campaign_id Y Y Y Y Y Y Y Y
fb_adset_name Y Y Y Y Y Y Y Y
fb_adset_id Y Y Y Y Y Y Y Y
fb_adgroup_name Y Y Y Y Y Y Y Y
fb_adgroup_id Y Y Y Y Y Y Y Y
af_ad_type Y Y Y N Y Y Y N
af_siteid Y Y Y Y Y Y Y Y
af_sub1 Y Y Y Y Y Y Y Y
af_sub2 Y Y Y Y Y Y Y Y
af_sub3 Y Y Y Y Y Y Y Y
af_sub4 Y Y Y Y Y Y Y Y
af_sub5 Y Y Y Y Y Y Y Y
http_referrer Y Y Y Y Y Y Y Y
click_url Y Y Y Y Y Y Y Y
af_cost_model Y N N N Y Y Y N
af_cost_value Y N N N Y Y Y N
af_cost_currency Y N N N Y Y Y N
cost_per_install Y N N Y Y Y Y Y
is_retargeting Y Y Y Y Y Y Y Y
re_targeting_conversion_type Y Y Y Y Y Y Y Y
country_code Y Y Y Y Y Y Y Y
city Y Y Y Y Y Y Y Y
ip Y Y Y Y Y Y Y Y
wifi Y Y Y Y Y Y Y Y
mac Y Y Y Y Y Y Y Y
operator Y Y Y Y Y Y Y Y
carrier Y Y Y Y Y Y Y Y
language Y Y Y Y Y Y Y Y
appsflyer_device_id Y Y Y Y Y Y Y Y
advertising_id Y Y Y Y Y Y Y Y
android_id Y Y Y Y Y Y Y Y
customer_user_id Y Y Y Y Y Y Y Y
imei Y Y Y Y Y Y Y Y
idfa Y Y Y Y Y Y Y Y
platform Y Y Y Y Y Y Y Y
device_brand Y Y Y Y Y Y Y Y
device_model Y Y Y Y Y Y Y Y
os_version Y Y Y Y Y Y Y Y
app_version Y Y Y Y Y Y Y Y
sdk_version Y Y Y Y Y Y Y Y
app_id Y Y Y Y Y Y Y Y
app_name Y Y Y Y Y Y Y Y
bundle_id Y Y Y Y Y Y Y Y
event_time Y Y Y Y Y Y Y Y
event_name Y Y Y Y Y Y Y Y
event_value Y Y Y Y Y Y Y Y
currency Y Y Y Y Y Y Y Y
download_time_selected_timezone Y Y Y Y Y Y Y Y
click_time_selected_timezone Y Y Y Y Y Y Y Y
install_time_selected_timezone Y Y Y Y Y Y Y Y
event_time_selected_timezone Y Y Y Y Y Y Y Y
selected_currency Y Y Y Y Y Y Y Y
revenue_in_selected_currency N N N N Y Y Y Y
cost_in_selected_currency Y Y Y Y N N N N

Push API Specific Parameters

Some Push API parameters are called differently than in the V5 reports. There are also several parameters that exist on Push API, but not on other V5 sources. You can find them in the table below. 

Push API Field Name V5 Field Name Description
fb_campaign_name N/A Facebook campaign name*
fb_campaign_id N/A Facebook campaign ID number*
fb_adset_name N/A Facebook ad set name*
fb_adset_id N/A Facebook ad set ID number*
fb_adgroup_name N/A Facebook ad group name*
fb_adgroup_id N/A Facebook ad group ID*
event_type N/A install/in-app-event
attribution_type N/A Organic or Regular(non-organic)
click_time attributed_touch_time Attributed touch time
download_time N/A Timestamp of the download click on the app store, as appears on the device (UTC timezone)
agency  af_prt Name of the attributed agency 
cost_per_install af_cost_value Cost in original currency
re_targeting_conversion_type retargeting_conversion_type Re-engagement / Re-attribution
appsflyer_device_id appsflyer_id Unique app installation identifier per device 
currency af_cost_currency USD
selected_currency N/A Currency specified in the event or for the app in the dashboard
revenue_in_selected_currency event_revenue_currency Revenue in the currency selected for the app in the dashboard
cost_in_selected_currency af_cost_value Cost in the currency selected for the app in the dashboard
download_time_selected_timezone N/A Time of download in the time zone selected for the app
click_time_selected_timezone attributed_touch_time Time of the ad click in the time zone selected for the app
install_time_selected_timezone install_time Time of the first app launch in the time zone selected for the app
event_time_selected_timezone event_time Time of the event occurrence in the time zone selected for the app
device_name N/A Name of the device as entered by the user - always appears as Null.

* All the "Facebook" parameters, such as fb_campaign_name, fb_campaign_id or fb_adgroup_id, only get values when the user is attributed to Facebook.

Push API Examples

Below you can find examples of Push API messages sent on various Android and iOS related scenarios for your reference.

Organic Install

Android iOS
attributed_touch_type:
app_version: 5.7.1
event_time: 2017-06-25 12:34:31
media_source: Organic
fb_campaign_id:
fb_adset_id:
currency:
sdk_version: 4.7.1
event_type: install
agency:
download_time_selected_timezone: 2017-06-24 06:34:45.000+0000
imei:
event_time_selected_timezone: 2017-06-25 12:34:31.267+0000
event_value:
app_id: com.greatapp
mac:
selected_currency: USD
fb_adgroup_id:
android_id:
cost_in_selected_currency:
install_time: 2017-06-25 12:34:31
fb_adgroup_name:
fb_adset_name:
attributed_touch_time:
is_retargeting: false
click_time_selected_timezone:
customer_user_id:
wifi: true
device_model: SM-G930L
language: ???
click_url:
attribution_type: organic
cost_per_install:
country_code: KR
af_siteid:
download_time: 2017-06-24 06:34:45
campaign:
app_name: great app
city: Bangeo-Dong
install_time_selected_timezone: 2017-06-25 12:34:31.267+0000
ip: 119.64.85.216
click_time:
af_sub2:
af_sub3:
af_sub1:
af_sub4:
af_sub5:
fb_campaign_name:
bundle_id: com.greatapp
event_name:
re_targeting_conversion_type:
advertising_id: 1f1cb970-00f7-4672-91db-6b4c********
platform: android
operator: LGU+
http_referrer:
af_keywords:
device_brand: samsung
carrier: LG U+
appsflyer_device_id: 1498286085929-59021898927********
os_version: 7.0

Non-Organic Install

Android iOS

attributed_touch_type: click
app_version: 5.9.0
event_time: 2017-06-25 12:34:46
af_ad_id:
media_source: goodsource_int
fb_campaign_id:
install_time_selected_timezone: 2017-06-25 12:34:46.529+0000
af_channel:
currency:
event_time_selected_timezone: 2017-06-25 12:34:46.529+0000
event_type: install
agency:
download_time_selected_timezone: 2017-06-25 12:34:17.000+0000
imei:
event_value:
af_ad:
selected_currency: USD
fb_adgroup_id:
android_id:
af_sub1: desktop
install_time: 2017-06-25 12:34:46
fb_adgroup_name:
fb_adset_name:
attributed_touch_time: 2017-06-25 12:33:33
af_cost_model:
is_retargeting: false
sdk_version: 4.7.1
mac:
af_cost_value:
app_id: com.greatapp
wifi: true
device_model: SM-T819Y
click_time: 2017-06-25 12:33:33
click_url: https://app.appsflyer.com/com.greatapp?pid=goodsource_int&c=hotel_page_footer&af_siteid=1456632&site_id=1456632&af_sub1=desktop
attribution_type: regular
af_ad_type:
cost_per_install:
country_code: SG
af_siteid: 1716632
download_time: 2017-06-25 12:34:17
campaign: hotel_page_footer
app_name: great app
city: Singapore
customer_user_id: 84a5111c-8142-45af-bebd-621c********
ip: 175.156.67.152
af_adset_id:
language: English
af_sub2:
af_sub3:
cost_in_selected_currency:
af_c_id:
af_sub4:
af_sub5:
fb_campaign_name:
bundle_id: com.greatapp
event_name:
click_time_selected_timezone: 2017-06-25 12:33:33.093+0000
re_targeting_conversion_type:
advertising_id: a8a5c84f-53fd-4803-b8e2-ab80********
fb_adset_id:
af_adset:
af_cost_currency:
platform: android
operator:
http_referrer: https://www.greatapp.com/
af_keywords:
device_brand: samsung
carrier: SGP-M1
appsflyer_device_id: 1498394057331-3915165764********
os_version: 6.0.1

Non-Organic In-App Event

Android iOS
fb_campaign_id:
fb_adgroup_name:
af_cost_model:
download_time: 2017-06-25 12:23:43
mac:
device_model: EVA-L19
agency:
android_id:
media_source: goodsource_int
http_referrer:
fb_adgroup_id:
download_time_selected_timezone: 2017-06-25 12:23:43.000+0000
af_ad:
af_sub2: EXP-RUN-ID-0
af_sub3: 9eaac647-483c-4c34-b2cd-*******
af_sub1: EXP-ID-0
click_url: http://greatapp.onelink.me/1640755593?pid=regoodsource_int&c=PromoOverlay_1764964&af_dp=greatapp%3A%2F%2Fpromocode%2F&target=449037%2C450238%*******&campaign_site_id=1456632&searchdatetype=False&af_siteid=1456632&af_sub1=EXP-ID-0&af_sub2=EXP-RUN-ID-0&af_sub3=9eaac647-483c-4c34-b2cd-********&af_click_lookback=1d
af_sub4:
af_sub5:
af_ad_id:
city: Lepar Hilir
af_cost_value:
attributed_touch_time: 2017-06-25 12:22:41
cost_per_install:
click_time_selected_timezone: 2017-06-25 12:22:41.167+0000
revenue_in_selected_currency: 140.25
attributed_touch_type: click
install_time: 2017-06-25 12:23:58
attribution_type: regular
fb_adset_name:
event_time: 2017-06-25 12:29:17
install_time_selected_timezone: 2017-06-25 12:23:58.455+0000
imei:
event_value: {"af_content_id":"298270","af_date_b":"08-07-2017","af_customer_user_id":"3f834809-5b7e-4eef-acd7-*******", "af_revenue":140.25,"af_price":140.25,"af_currency":null}
app_version: 5.9.0
sdk_version: 4.7.1
re_targeting_conversion_type:
af_keywords:
os_version: 7.0
af_adset:
operator:
bundle_id: com.greatapp
event_time_selected_timezone: 2017-06-25 12:29:17.557+0000
ip: 113.210.68.52
language: English
event_name: af_initiated_checkout
is_retargeting: false
appsflyer_device_id: 1498393423958-*************
advertising_id: f52f9ffc-2c9f-4319-94be-*************
customer_user_id: 3f834809-5b7e-4eef-acd7-*************
af_ad_type:
af_cost_currency:
carrier: MY MAXIS
wifi: false
af_channel:
campaign: PromoOverlay_1764964
af_siteid: 1731669
click_time: 2017-06-25 12:22:41
fb_campaign_name:
platform: android
country_code: MY
fb_adset_id:
af_c_id:
app_name: great app
af_adset_id:
app_id: com.greatapp
selected_currency: USD
device_brand: HUAWEI
currency:
event_type: in-app-event

Retargeting In-App Event - Facebook Re-Engagement

Android iOS
fb_campaign_id: 6066880136818
fb_adgroup_name: |Auto Feed|T:DAT-iOS|O:All|L:TH-TH|A:Hotel|R:2-4 Day|
download_time: 2017-05-20 11:48:33
mac:
device_model: CPH1607
agency:
platform: android
media_source: Facebook Ads
fb_adgroup_id: 6066880147218
download_time_selected_timezone: 2017-05-20 11:48:33.000+0000
af_ad:
app_name: great app
af_sub3:
af_sub1:
click_url:
click_time_selected_timezone:
install_time_selected_timezone: 2017-06-04 11:47:54.623+0000
af_sub5:
af_ad_id:
af_cost_value:
attributed_touch_time: 2017-05-27 22:17:10
cost_per_install:
click_time: 2017-05-27 22:17:10
language: ???
attributed_touch_type: click
install_time: 2017-06-04 11:47:54
attribution_type: regular
fb_adset_name: |Auto Feed|T:DAT-iOS|O:All|L:TH-TH|A:Hotel|R:2-4 Day|
android_id:
event_time: 2017-06-25 12:29:14
af_sub4:
operator:
appsflyer_device_id: 1495280913891-*************
af_cost_currency:
app_version: 5.9.0
sdk_version: 4.7.1
fb_adset_id: 6066880141618
af_keywords:
fb_campaign_name: |Auto Feed|T:DAT|L:TH-TH|
af_adset:
re_targeting_conversion_type: re-engagement
bundle_id: com.greatapp
event_time_selected_timezone: 2017-06-25 12:29:14.358+0000
ip: 175.136.225.45
revenue_in_selected_currency:
event_name: af_search
is_retargeting: true
imei:
advertising_id: b31bd790-209f-41d0-946f-*************
customer_user_id: 8ce24e82-8530-40cb-88f9-*************
af_ad_type:
event_value: {"af_room_no":"1","af_content_id":"27758","af_date_a":"27-06-2017", "af_currency":null,"af_date_b":"28-06-2017","af_language_id":"22"}
af_sub2:
carrier: MY MAXIS
wifi: true
campaign: |Auto Feed|T:DAT|L:TH-TH|
af_siteid:
af_cost_model:
os_version: 6.0.1
af_channel: Facebook
country_code: MY
city: Kampung Kurnia Jaya
af_c_id:
af_adset_id:
app_id: com.greatapp
selected_currency: USD
device_brand: OPPO
currency:
event_type: in-app-event
 

How to Count Re-engagements?

Push API can automatically send re-attribution events in real time, if the Retargeting installs box is checked. You can check the Retargeting in-app events box to get by push all in-app events occurring during the re-engagement window.

However, the initial act of the re-engagement, where existing users launch the app after clicking a link, is not reported automatically.

Whenever deep linking occurs for an existing user, the onAppOpenAttribution method is called. Therefore, if you need to know when re-engagements occur, send an event from the onAppOpenAttribution method, signifying a deeplinking re-engagement event.

Click here to see the recommended structure of the "re-engage" event.

What is the Supported API Security?

All Push API messages are sent using secure crypted https connections.

For more details go here

Where is the Pushed Facebook Data?

By default Facebook does not release raw user-level data, unless you accept Facebook's Terms of Service.
By doing so, you enable the sending of user-level data of installs coming from Facebook, via Push API (and to other raw data resources, as well).

Was this article helpful?
7 out of 11 found this helpful

Comments

0 comments

Please sign in to leave a comment.