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

At a glance: Push attribution event data in real-time by API for use in your IT systems. 

4409_Push_API_V2-01.png

Push API V2.0

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 be deprecated and is no longer being updated. The sunset date will be announced. 
  • 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
(✓ = available, - not applicable)

Campaign type

Event type

(Conversion type)

value of is_
retargeting

value of retargeting_

conversion_

type

Non-organic Organic Retargeting
User acquisition Install False    -
User acquisition  Install in-app events False    -

Retargeting

Re-engagement True   - -
Retargeting  Re-engagement in-app events True re-engagement - -
Retargeting  Re-attribution  True re-attribution - -
Retargeting  Re-attribution in-app events True re-attribution -

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's 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. 

Before you begin

Prepare the following: 

  • 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. Thissdf 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. 

To add a Push API endpoint:

  1. The account admin needs to log into AppsFlyer. Note: Team members have view-only access. 
  2. Go to Integration > API Access.
    The API Access window opens. 
  3. Scroll down to the Push API section.
    The Push API endpoint section displays.
    PushAPi.png
  4. Click Add Postback.
    You can configure up to 6 push API endpoints.
  5. Select an HTTP method: POST or GET
  6. Enter the Postback URL. 
  7. Select Push API version: (default) 2.0 
  8. Select one or more event types to be sent to the endpoint URL. 
  9. Click Save
    The Push API is now active
    Conversion data is sent to the endpoint.
  10. Test the endpoint using the procedure that follows.
  11. (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

The following POST message is sent as a test message

{                  
  "idfv": "123456789",
  "device_category": "phone",
  "af_sub1": "sub1-12345",
  "customer_user_id": "Customer User ID",
  "is_lat": null,
  "contributor_2_af_prt": "attributionagency",
  "bundle_id": "bundleIdentifier_test",
  "gp_broadcast_referrer": "",
  "contributor_2_touch_time": "2019-12-31 00:05:42.805",
  "contributor_3_touch_type": "click",
  "event_source": "SDK",
  "af_cost_value": "10",
  "contributor_1_match_type": "id_matching",
  "app_version": "app_version",
  "contributor_3_af_prt": "attributionagency",
  "custom_data": null,
  "contributor_2_touch_type": "click",
  "gp_install_begin": "2019-12-31 00:07:14.000",
  "city": "Redmond",
  "amazon_aid": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "gp_referrer": "af_tranid=000712-31122019254604&pid=pdsagency_int&c=pushapi_v2",
  "af_cost_model": "CPI",
  "af_c_id": "cid12345",
  "attributed_touch_time_selected_timezone": "2019-12-31 00:06:32.891+0000",
  "selected_currency": "EUR",
  "app_name": "com.pds.pushapi2.v2.transparent.com",
  "install_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "postal_code": "98052",
  "wifi": false,
  "install_time": "2019-12-31 00:07:14.961",
  "operator": "ORANGE",
  "attributed_touch_type": "click",
  "af_attribution_lookback": "25d",
  "keyword_match_type": null,
  "af_adset_id": "adset12345",
  "device_download_time_selected_timezone": "2019-12-31 00:07:14.961+0000",
  "contributor_2_media_source": "contrib2",
  "contributor_2_match_type": "id_matching",
  "api_version": "2.0",
  "attributed_touch_time": "2019-12-31 00:06:32.891",
  "revenue_in_selected_currency": null,
  "is_retargeting": false,
  "country_code": "US",
  "gp_click_time": "2019-12-31 00:07:12.000",
  "contributor_1_af_prt": "attributionagency",
  "match_type": "id_matching",
  "appsflyer_id": "e126a3b3-3406-4196-a964-563c9ae44ff8",
  "dma": "819",
  "http_referrer": "https://www.amazon.com/gp/bestsellers/gift-cards/ref=sv_gc_0",
  "af_sub5": "sub5-12345",
  "af_prt": "attributionagency",
  "event_revenue_currency": null,
  "store_reinstall": null,
  "install_app_store": null,
  "media_source": "pdsagency_int",
  "deeplink_url": null,
  "campaign": "pushapi_v2",
  "af_keywords": "keywords12345",
  "region": "NA",
  "cost_in_selected_currency": "1000",
  "event_value": null,
  "ip": "20.168.174.166",
  "oaid": null,
  "event_time": "2019-12-31 00:07:14.961",
  "is_receipt_validated": null,
  "contributor_1_campaign": "camp1",
  "af_sub4": "sub4-12345",
  "imei": null,
  "contributor_3_campaign": "camp3",
  "event_revenue_usd": null,
  "af_sub2": "sub2-12345",
  "original_url": "https://app.appsflyer.com/com.pds.pushapi2.v2.transparent.com?c=pushapi_v2&pid=pdsagency_int&clickid=click12345&af_ref=000632-31122019&advertiserId=9173fe74-0578-4658-a461-ebb0b4fce6d6&android_id=3e06b4caebc19356&sha1_android_id=sha12345&af_siteid=136396&af_sub_siteid=sub_siteid12345&af_c_id=cid12345&af_adset=adset12345&af_adset_id=adset12345&af_ad=ad12345&af_ad_id=adid12345&af_ad_type=adtype12345&af_channel=channel12345&af_keywords=keywords12345&is_retargeting=False&af_dp=ebay%3A%2F%2Fshoppingcart&af_web_dp=www.dp.com&af_sub1=sub1-12345&af_sub2=sub2-12345&af_sub3=sub3-12345&af_sub4=sub4-12345&af_sub5=sub5-12345&af_cost_model=CPI&af_cost_value=10&af_cost_currency=EUR&sha1_advertising_id=sha12345&sha1_el=sha12345&af_installpostback=false&af_force_dp=true&af_chrome_lp=true&af_ec=1&af_click_lookback=25d&af_viewthrough_lookback=1h&af_reengagement_window=2d&af_prt=attributionagency",
  "contributor_2_campaign": "camp2",
  "android_id": "3e06b4caebc19356",
  "contributor_3_media_source": "contrib3",
  "af_adset": "adset12345",
  "af_ad": "ad12345",
  "state": "WA",
  "network_account_id": null,
  "device_type": "Samsung::SH-220",
  "idfa": null,
  "retargeting_conversion_type": null,
  "af_channel": "channel12345",
  "af_cost_currency": "EUR",
  "contributor_1_media_source": "contrib1",
  "keyword_id": null,
  "device_download_time": "2019-12-31 00:07:14.961",
  "contributor_1_touch_type": "click",
  "af_reengagement_window": "2d",
  "af_siteid": "136396",
  "language": "English",
  "app_id": "com.pds.pushapi2.v2.transparent.com",
  "contributor_1_touch_time": "2019-12-31 00:06:07.847",
  "event_revenue": null,
  "af_ad_type": "adtype12345",
  "carrier": "carrier",
  "event_name": "install",
  "af_sub_siteid": "sub_siteid12345",
  "advertising_id": "9173fe74-0578-4658-a461-ebb0b4fce6d6",
  "os_version": "6.0",
  "platform": "android",
  "af_sub3": "sub3-12345",
  "contributor_3_match_type": "id_matching",
  "selected_timezone": "UTC",
  "af_ad_id": "adid12345",
  "contributor_3_touch_time": "2019-12-31 00:05:17.757",
  "user_agent": "Dalvik/1.6.0 (Linux; U; Android 6.0; Redmi Note 4 Build/KOT49I.F320S22g",
  "is_primary_attribution": null,
  "sdk_version": "v4.8.0",
  "event_time_selected_timezone": "2019-12-31 00:07:14.961+0000"
}

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, displays as2019-09-17 00:09:25.123 An event took place at 14:00 Tokyo time. The event time is converted to UTC which is 05:00. The time recorded is the UTC time. 
  • 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. An event took place at 14:00 Tokyo time. The event time shows is recorded as 14:00+09:00. 09:00 is the Tokyo time zone. 
Unique Push 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
 
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.

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  
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  
user_agent User Agent  
wifi WIFI  

Troubleshooting, limitations & traits

Duplicate retargeting in-app events

Retargeting in-app events are duplicated when a purchase event takes place as part of a retargeting campaign during the UA re-engagement window. This is done to attribute revenue to both the UA media source and the retargeting media source. 

You will only get duplicate event if you have enabled both:

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

In-app events attributed to the UA media source (install in-app events) as part of a retargeting campaign have the field is_primary_attribtuion=false. 

 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 in-app purchase event is sent twice with the following details:

Retargeting in-app event fields
Event type Media source is_retargeting re_targeting conversion_type is_primary_
attribution 
Install in-app event ua_network True re-engagement or reattribution  False
Retargeting in-app event retar_network True re-engagement or reattribution  True


How do I identify duplicate retargeting events?

The is_primary_attribution boolean field identifies primary and secondary media sources in retargeting campaigns:

  • False: identifies the original UA media source. Note: This is the only scenario where the value is false. 
  • True: identifies the re-engagement 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 and the UA source is secondary. 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.