Push API real-time raw-data (V2)

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. 
  
  • Android_Push_API_ V2.0_json
  • iOS_Push_API_V2.json

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. 

• Raw data fields available via Push API
• Detailed description of all raw data fields in AppsFlyer irrespective of the delivery method

Ensure that your server complies with the requirements listed here. 

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

Endpoint 

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

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. 

     

     • 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. If the test fails, ensure that have allowlisted AppsFlyer IP addresses. 
2. Check that the endpoint received the test message.
   A copy of the message sent follows.

{                  
  "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"
}

Deleting an 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. 

Migrating an endpoint from V1.0 to V2.0

To 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. 

     

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

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.  

If you don't receive the test message and you restrict access to your servers by IP address: ensure that you have allowlisted all of the AppsFlyer IP addresses. 

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. 

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

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.

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