Push API V2.0 real-time raw data (open beta)

At a glance: Attribution event data is pushed to you in real-time for use in your IT systems. You select the attribution events and the data is sent to your web service endpoint.

Push API V2.0

4409_Push_API_V2-01.png

  Push API news

  • Push API V2.0 is aligned with AppsFlyer raw data V5.0 specification used by other data delivery tools in AppsFlyer. It has over 40 additional attribution fields. As new fields are added they are made available rapidly in Push API V2.0.
  • Push API V1.0 will no longer be updated and will be discontinued.
  • Developer! Migration guide Push API V1.0 to Push API V2.0

Push API is used to get Attribution data in real-time so that you can combine in-house user data with the real-time attribution data from AppsFlyer. Use the data to follow user journeys and to perform real-time analytics and segmentation. 

If your app flow depends on attribution data in real-time (less than five seconds) consider using conversion data.

For more information about AppsFlyer data tools see: Choosing AppsFlyer data delivery tools, Using Push and Pull API together

Example JSON output files:

Push API features

Event types supported by Push API
Campaign type Event type Non-organic Organic Retargeting
User acquisition Install  
User acquisition  Install in-app events  
Retargeting Re-engagement    
Retargeting  Re-engagement in-app events    
Retargeting  Re-attribution     
Retargeting  Re-attribution in-app events    

Data freshness

Push API messages are sent in real-time. 

Technology

    • RESTful API, POST and GET methods supported
    • POST message responses are contained in a JSON

 Caution

Some media sources, restrict the use of user-level data and the sharing of this data with third parties. Ensure that you comply with the media source terms of use.
For example, Facebook, Twitter, Snapchat, Pinterest.

Implementing Push API

Setting up Push API

Implementation guidelines 

  • Additional fields may be added to the JSON structure from time to time without prior notice. Follow this article to be informed of changes.
  • If your endpoint host fails to accept the Push API messages they can't be resent. If you lose Push API messages, use pull API to fill any gaps. 

Checklist

Complete this checklist before you setup Push API. 

  • Whitelist IPs: Whitelist AppsFlyer IP addresses so that they can communicate with the endpoint defined in the URL. List of AppsFlyer IP addresses.
  • TLS support:
  • Ports: 80, 443
  • Endpoint:
    • Is a valid domain name
    • Configured to return HTTP status code 200 indicating successful completion. Note: No other status code is allowed. This includes other 2XX codes. 
    • The same endpoint can be used once per app. 
    • When using the GET method, do not add query parameters to the URL if the endpoint is hosted by third-party providers.
    • API key parameters aren't supported.
  • Facebook campaigns:  If you want to receive data, attributed to Facebook, you need to accept the Facebook terms of service. If you do not do so, Facebook data is not sent by Push API. 

Setting up Push API

To add a Push API endpoint:

  1. In AppsFlyer, go to Integration > API Access.
    The API Access window opens. 
  2. Scroll down to the Push API section.
    The Push API endpoint section displays.
    PushAPi.png
  3. Click Add Postback.
    You can configure up to 6 push API endpoints.
  4. Select an HTTP method: POST or GET
  5. Enter the Postback URL. 
  6. (Optional) Select Push API version: (default) 2.0 
  7. Select one or more event types to be sent to the endpoint URL. 
  8. Click Save
    The Push API is now active
    Conversion data is sent to the endpoint.
  9. Test the endpoint using the procedure that follows.
  10. (Optional) If you want to receive data attributed to Facebook by Push API, ensure that you have accepted the Facebook terms of service.  

To test the endpoint:

  1. Click Send Test. 
    A test result message displays below the Send Test button. 
    A test message is sent to the endpoint.
  2. Check that the endpoint received the test message.
    A copy of the message sent follows.

Test POST and GET API messages

At present, the message sent as a test message is the Push API V1.0 message. What's important, is that you receive the message and not the content. 

Removing postbacks

To remove a Postback:

  1. Go to Integration > API Access.
    Scroll down to the Push API access section. 
  2. Click Remove Postback.
  3. Click Save.
    The postback is removed. 

Push API message structures

The Push API response depends on the HTTP method:

  • GET: data parameters are appended to the URL string
  • POST: data parameters are contained in the message body in JSON format

Push API fields

Push API messages contain the fields as described here. Additional fields will be added from time to time as these are added to the AppsFlyer platform Your import/parsing mechanisms should take this into account. 

Format of timestamp fields:

  • For timestamp fields in UTC: format yyyy-mm-dd hh:mm:ss.sss. For example, 2019-09-17 00:09:25.123 
  • For timestamp fields in selected time zone: format yyyy-mm-dd hh:mm:ss.±th:tm. For example 2019-01-20 04:51:16.000+0000 
Unique API fields
Display name V2.0 name Remarks 
Selected currency selected_currency This is the app-level setting in force at the time the API message is sent.
Revenue in selected currency revenue_in_selected_
currency
 
Cost In Selected Currency cost_in_selected_
currency
 
Device Download Time Selected Timezone device_download_time_selected_
timezone
Up until Feb 3, 2020 an additional field, download_time_selected timezone is also available. 
Attributed Touch Time Selected Timezone attributed_touch_time_
selected_timezone
 
Install Time Selected Timezone install_time_selected_
timezone
 
Event Time Selected Timezone event_time_selected_
timezone
 
Selected Timezone selected_timezone This is the app-level setting in force at the time the API message is sent.
Deep Link URL deeplink_url Available from Q1-2020
OAID oaid Available from Q1-2020
Keyword ID keyword_id Available from Q1-2020
Store Reinstall store_reinstall  Available from Q1-2020

Full list of Push API fields

Push API V2.0 name Push API Display name Comments
advertising_id Advertising ID  
af_ad ad  
af_ad_id Ad ID  
af_ad_type Ad Type  
af_adset Adset  
af_adset_id Adset ID  
af_attribution_lookback Attribution Lookback Window  
af_c_id Campaign ID  
af_channel Channel  
af_cost_currency Cost Currency  
af_cost_model Cost Model  
af_cost_value Cost Value  
af_keywords Keywords  
af_prt Partner  
af_reengagement_window Reengagement Window  
af_siteid Site ID  
af_sub_siteid Sub Site ID  
af_sub1 Sub Param 1  
af_sub2 Sub Param 2  
af_sub3 Sub Param 3  
af_sub4 Sub Param 4  
af_sub5 Sub Param 5  
amazon_aid Amazon Fire ID  
android_id Android ID  
api_version API Version  
app_id App ID  
app_name App Name  
app_version App Version  
appsflyer_id AppsFlyer ID  
attributed_touch_time Attributed Touch Time  
attributed_touch_time_selected_timezone Attributed Touch Time Selected Timezone Push API specific
attributed_touch_type Attributed Touch Type  
bundle_id Bundle ID  
campaign Campaign  
carrier Carrier  
city City  
contributor_1_af_prt Contributor 1 Partner  
contributor_1_campaign Contributor 1 Campaign  
contributor_1_match_type Contributor 1 Match Type  
contributor_1_media_source Contributor 1 Media Source  
contributor_1_touch_time Contributor 1 Touch Time  
contributor_1_touch_type Contributor 1 Touch Type  
contributor_2_af_prt Contributor 2 Partner  
contributor_2_campaign Contributor 2 Campaign  
contributor_2_match_type Contributor 2 Match Type  
contributor_2_media_source Contributor 2 Media Source  
contributor_2_touch_time Contributor 2 Touch Time  
contributor_2_touch_type Contributor 2 Touch Type  
contributor_3_af_prt Contributor 3 Partner  
contributor_3_campaign Contributor 3 Campaign  
contributor_3_match_type Contributor 3 Match Type  
contributor_3_media_source Contributor 3 Media Source  
contributor_3_touch_time Contributor 3 Touch Time  
contributor_3_touch_type Contributor 3 Touch Type  
cost_in_selected_currency Cost In Selected Currency Push API specific
country_code Country Code  
custom_data Custom Data  
customer_user_id Customer User ID  
deeplink_url Deep Link URL Available from Q1-2020
device_category Device Category  

device_download_time 

Device Download Time Up until Feb 3, 2020 an additional field, download_time is also available. 
device_type Device Type  
dma DMA  
device_download_time_selected_timezone Device Download Time Selected Timezone

Push API specific.

Up until Feb 3, 2020 an additional field, download_time_selected timezone is also available.

event_name Event Name  
event_revenue Event Revenue  
event_revenue_currency Event Revenue Currency  
event_revenue_usd Event Revenue USD  
event_source Event Source  
event_time Event Time  
event_time_selected_timezone Event Time Selected Timezone Push API specific
event_value Event Value  
gp_broadcast_referrer GP Broadcast Referrer  
gp_click_time Google Play Click Time  
gp_install_begin Google Play Install Begin Time  
gp_referrer Google Play Referrer  
http_referrer HTTP Referrer  
idfa IDFA  
idfv IDFV  
imei IMEI  
install_app_store Install App Store  
install_time Install Time  
install_time_selected_timezone Install Time Selected Timezone Push API specific
ip IP  
is_LAT Is LAT Available from Q4/2019
is_primary_attribution Is Primary Attribution  
is_receipt_validated Is Receipt Validated  
is_retargeting Is Retargeting  
keyword_id Keyword ID Available from Q4/2019
keyword_match_type Keywords Match Type  
language Language  
match_type Match Type  
media_source Media Source  
network_account_id Network Account ID  
oaid OAID  
operator Operator  
original_url Original URL  
os_version OS Version  
platform Platform  
postal_code Postal code  
region Region  
retargeting_conversion_type Retargeting Conversion Type  
revenue_in_selected_currency Revenue In selected currency Push API specific
sdk_version SDK Version  
selected_currency Selected Currency Push API specific
selected_timezone Selected Timezone Push API specific
state State  
store_reinstall (False=Download, True=Redownload) Store Reinstall Available from Q4/2019
user_agent User Agent  
wifi WIFI  

Troubleshooting, limitations & traits

Duplication of retargeting events

In some cases, retargeting events are duplicated. This occurs when an in-app purchase event takes place as a result of a retargeting campaign during the UA re-engagement window.

In this case, two attribution events are generated to attribute the revenue to the media source that brought the install and the media source that brought the re-engagement. 

You will only get two Push API's if you have enabled Push APIs for both

  • install in-app events
  • retargeting in-app events

 Example

  • A user installs example_app, which is attributed to ua_network
  • Later the user re-engages with example_app's retargeting campaign on retar_network and makes a purchase.

The event is sent twice with the following details:

Unique API fields
Event type Media source is_retargeting re_targeting conversion_type
Non-organic ua_network False null (no value)
Retargeting  retar_network True re-engagement


How do I identify duplicate retargeting events?

Use the is_primary_attribution boolean field which indicates the primary and secondary media sources as follows. 

  • In UA campaigns the value can only be true because the UA media source is the only media source.
  • In retargeting campaigns:
    • True: identifies the re-engagement media source 
    • False: identifies the original UA media source

This reason for this is as follows: If a user, as a result of a retargeting campaign,  engages with the campaign, a re-engagement window opens. The re-engagement media source is regarded as the primary media source when the re-engagement window is open. After the window closes, the original UA media source reverts to being primary. 

Missing Facebook data

By default, Facebook does not release raw user-level data, until you accept the Facebook 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).

Missing push messages and CloudFront

Are you using Amazon CloudFront as your endpoint? If so, check if CloudFront is rejecting the message with reject code 421. If this is the case, see Choosing How CloudFront Serves HTTPS Requests

Limitations & Traits

Traits
Trait Remarks 
Ad networks Not for use by ad networks. 
Agencies Not for use by agencies
App-specific time zone Supported
App-specific currency  Supported
Size limitations Not applicable
Organic  Yes
Non-organic Yes
Data freshness Real-time
Historical data Not supported. Event data is sent after configuring Push API. If you need historical raw data use Pull API. 
Team member access Team members can view Push API settings but aren't able to make changes. 
Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.