Using Push API V2.0 real-time raw-data

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.pngPush 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 topic 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)

Attribution type

Topic

conversion_type field

Non-organic

(campaign_type field)

Organic (campaign_type field)
User acquisition Install(*) Install UA Organic
User acquisition  Install in-app events Install UA Organic

Retargeting

Re-engagement Re-engagement Retargeting -
Retargeting  Re-engagement in-app events Re-engagement Retargeting -
Retargeting  Re-attribution  Reinstall Retargeting -
User acquisition  Reinstall Reinstall UA Organic
Retargeting Re-attribution in-app events Reinstall Retargeting -
* Some installs relating to view-through attribution are attributed to the restricted media source.

Message structure and unique fields

The Push API message 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 
  • The examples that follow contain null/empty fields. In the future, we plan to stop sending empty/null fields. 

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 (relative to other data delivery tools)
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 

Setting up Push API

 Caution

Don't use Push API for sending data to third-parties because:

  • By doing so you may be in breach of privacy regulations like CCPA if the user opted out of sending their data to third parties.
  • 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.  To set up a new endpoint
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.
Allowlist AppsFlyer servers

Allowlist 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.
  • We dont' send empty/null fields
 
5

In-app event type

 

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

  • Select one or more or all in-app events. Note! If the event does not display in the list search for it. 
  • If you select all, then new in-app events are added automatically. 
  • You can only select an in-app event after it has been recorded at least once. 
  • 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. 
  • Only the admin can make changes to API settings. Team members can view Push API settings.
AppsFlyerAdmin_us-en.png 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.  If you get the message this URL is not safe, contact AppsFlyer support.
  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 all to clear all optional fields.
      • We don't send null/empty fields and the associated key. Take this into account when planning your import/parsing processes.
  7. Select one or more (up to 52 events) or  All in-app events.
    • 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/

AppsFlyerAdmin_us-en.png 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 an endpoint

 AppsFlyerAdmin_us-en.pngTo 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. 

Migrating an endpoint from V1.0 to V2.0

AppsFlyerAdmin_us-en.pngTo migrate an endpoint from V1.0 to V2.0:

  1. Go to Integration > API Access. Scroll down to the Push API section.
    The Push API section displays.
  2. Locate the endpoint to migrate.
  3. Select the fields to populate the Push API message. 
    • 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 all to clear all optional fields.
      • In the near future, we will stop sending null/empty fields and the associated key. Take this into account when planning your import/parsing processes.
  4. Select one or more (up to 52 events) or  All in-app events.
    • 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. 
  5. Click Save
    • Push API has been migrated. 
    • Conversion data continue being sent to the endpoint.

Endpoint error messages

Symptom: The message this URL is not safe displays when you set the endpoint URL.

Action required: Contact AppsFlyer support; include the app ID, endpoint URL, and a screenshot of the error message.  

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?