1. Help Center
  2. Reporting
  3. Reporting APIs

Push API V2.0 real-time attribution event reporting

Avatar
Gray Goldstein
Last update:
  • Advertisers
  • Developers
Push API 2.0Migrate V1.0-V2.0
At a glance: In real-time, push attribution event data to your server-side endpoints. Use the data in your IT systems. 

4409_Push_API_V2-01.png Push API V2.0

Push API news

  • Push API V2.0 aligns with AppsFlyer raw data V5.0 specification.
    • Additional fields: Over 40 fields added. As new fields are added to the platform, they are made available rapidly in Push API V2.0.
    • Field selection: Select the fields to send to reduce the size of Push API messages.
    • In-app event filtering: Select the in-app events sent to reduce processing.
  • Push API V1.0 is deprecated and sunsets on August 31, 2020.
  • Developer migration guide Push API V1.0 to Push API V2.0

 About Push API

Push API sends attribution event messages in real-time to your server-side endpoints. Doing so enables you to follow user journeys via multiple environments and touchpoints.

The volume of data sent to endpoints can be reduced by limiting:

  • The message and in-app event types selected.
  • The fields selected.

Other AppsFlyer data delivery solutions that may interest you:

Event message types

 Event message types available
(✓ = available, - not applicable)
Campaign 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 -  - ✓

Message structure and unique fields

The Push API message depends on the HTTP method:

Fields available

  • 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 the selected time zone: format yyyy-mm-dd hh:mm:ss.sss±th:tm. For example 2019-01-20 04:51:16.000+0000. An event took place at 14:00 Tokyo time. The event time shown 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.

Push API fields available

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  

Setting up Push API

 Caution

Some media sources, restrict how user-level data provided by them is used, shared with third parties, or both. Ensure that you comply with the media source's terms of use.
For example, Facebook, Twitter, Snapchat, Pinterest.

To setup Push API, complete the action list.

Push API action list
Action No.  Procedure
1

Complete the server-side requirements checklist
2

Plan the endpoint settings using the planning checklist
3

Configure the endpoint

Server-side requirements (your server)

Ensure that your server complies with the requirements listed here. 

Server-side requirements
Endpoint URL
  • Valid domain name
  • The same endpoint can be used once per app. 
  • Maximum number of endpoints per app: 6
Endpoint return code On receipt of a message, the endpoint must return an HTTP 200 status code.
Whitelist AppsFlyer servers

Whitelist AppsFlyer server IP addresses to ensure communication with the endpoint.
TLS versions
Ports 

Ports: 80, 443

Push API planning checklist

  • Use that checklist that follows to plan the endpoint settings. The numbers in the figure match the row numbers in the checklist.

Endpoint 

PushAPI_us-en.png

Endpoint planning table

No.

Setting

 Details Your setting
1

Method

 POST or GET  

2

Endpoint URL

 -  
3 Event message types
  • Select at least one event message type.
  •  To select in-app event messages, you need to record an in-app event. Until you do so, you can't select in-app event messages. 

InappSelectionDisabled_us-en.png

 

4

Fields 

The list of fields is common to all message types

Select the fields required.

  • The most common fields are pre-selected by default.
  
5

In-app event types

 Caution!

If you filter by in-app events meaning you don't Select All, you must add new in-app events manually. This is not the case for Select All.

Filter by in-app events to reduce traffic sent to your endpoint.

  • Up to 52 in-app events can be selected or Select All. This means that if you have more than 52 in-app events, and you wish to select more then 52 you must Select All.
  • You can only select an in-app after it has been recorded at least once. 
  • You can search for events if you have more 52 events.mceclip1.png

 
Facebook Do you intend to send data of users attributed to Facebook? 

To receive Facebook data, Ensure that you have accepted the Facebook terms of service. 

 

Setting up and managing endpoints

  • This section contains procedures to add, test, modify, and delete endpoints. 
  • Team members can view Push API settings but not make changes. 
To add a Push API endpoint:
  1. Go to Integration > API Access. Scroll down to the Push API section.
    The Push API section displays.
  2. Click Add Endpoint. 
  3. Select an HTTP method: POST or GET
  4. Enter the Endpoint URL. 
  5. Select one or more event types. Note! If the in-app event messages are disabled, it means no in-app events have been recorded to now. 
  6. Select the fields to populate the Push API message. Note:
    • Mandatory fields always sent: App ID, Event name, Event time, IDFA (iOS) or Advertising ID (Android)
    • Use the controls depicted in the following figure to select optional fields. 

      PushAPIFieldSelect1.jpg

      • The most frequently selected fields are pre-selected. They can be clear selected.
      • Select optional fields as needed.
      • Use Clear Select all to clear all optional fields.
  7. Select up to 52 or Select All in-app events.
    • Caution! If you don't Select All, you need to add new in-app events manually. 
    • The list is populated by event types that have already been recorded. If an event is missing, send an event having this type using a test device. 
  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. If you want to receive events attributed to Facebook, you must first accept 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_broadcastreferrer": "",
  "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"
}

Changing an endpoint

To modify endpoint settings:

  1. Go to Integration > API Access.
    Scroll down to the Push API section.
    The Push API section displays.
  2. Locate the endpoint to be modified.
  3. Make the modifications.
  4. Click Save.

Deleting and endpoint

To delete an endpoint:

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

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. 

In-app event message selection is disabled

InappSelectionDisabled_us-en.png

  • In-app event messages can only be selected after one in-app event has been recorded.
  • Use a test device to generate an in-app event or use the S2S API to do so manually. 

Missing Facebook data

By default, Facebook does not release raw user-level data until you accept the Facebook Terms of Service. 
Once you accept the terms, user-level data coming from Facebook and other raw data sources is sent via Push API.

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?

Articles in this section

Related articles