At a glance: In real-time, push attribution event data to your server-side endpoints.
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 topic and in-app event types selected.
- The fields selected.
Other AppsFlyer data delivery solutions that may interest you:
- If your app flow depends on the availability of real-time attribution data in less than five seconds, check if conversion data is not preferable.
- Comparing AppsFlyer data delivery tools
Event message types
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 example2019-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.
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
- Raw data fields available via Push API
- Detailed description of all raw data fields in AppsFlyer irrespective of the delivery method
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.
Action No. | To set up a new endpoint |
---|---|
1 | |
2 | |
3 |
Server-side requirements (your server)
Ensure that your server complies with the requirements listed here.
Endpoint URL |
|
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 in your firewalls and security systems 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
No. |
Setting |
Details | Your setting |
---|---|---|---|
1 |
Method |
POST or GET | |
2 |
Endpoint URL |
- | |
3 | Event message types |
|
|
4 |
Fields The list of fields is common to all message types |
Select the fields required.
|
|
5 |
In-app event type
|
Filter by in-app events to reduce traffic sent to your endpoint. |
|
Do you intend to send data of users attributed to Facebook? |
|
|
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.

- Go to Integration > API Access. Scroll down to the Push API section.
The Push API section displays. - Click Add Endpoint.
- Select an HTTP method: POST or GET
- Enter the Endpoint URL. If you get the message this URL is not safe, contact AppsFlyer support.
- 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.
- 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.
- 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.
- Click Save
The Push API is now active
Conversion data is sent to the endpoint. - Test the endpoint using the procedure that follows.
- If you want to receive events attributed to Facebook, you must first accept Facebook terms of service.
To test the endpoint:
- 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. - 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:
- Go to Integration > API Access.
Scroll down to the Push API section.
The Push API section displays. - Locate the endpoint to be modified.
- Make the modifications.
- Click Save.
Deleting an endpoint
To delete an endpoint:
- Go to Integration > API Access.
Scroll down to the Push API access section. - Click Delete endpoint.
- 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:
- Go to Integration > API Access. Scroll down to the Push API section.
The Push API section displays. - Locate the endpoint to migrate.
- 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.
- 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.
- 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
Test message sending fails
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.
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:
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
- 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
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. |
Migrating from Push API V1.0 to Push API V2.0
This section is for app owner BI/IT engineers responsible for migrating Push API V1.0 to Push API 2.0.
In planning the migration from V1.0 to V2.0 take into consideration, the field changes detailed in this section.
What's changed
Field level changes, detailed in the tables that follow:
- Removed fields: fields that are replaced by AppsFlyer raw data fields
- Renamed fields: field names are now aligned with AppsFlyer raw data names
- Additional (new) fields: fields that were not available in V1.0. You can select which fields are sent in messages.
- Unique fields to Push API: found only in Push API
Endpoints are unchanged:
- The change to API V2.0 relates to fields only, meaning that the API JSON/query parameters are unchanged
- There is no change to the Push API interface mechanism or endpoints
Future field additions:
- I field additions in Appsflyer will be made available rapidly in Push API 2.0. Push API V1.0 is deprecated and will be sunset on August 31, 2020.
- This will not result in a change to the API version number
- Ensure that you parsing/import mechanisms accommodate additional fields with ease
Set up Push API V2.0 endpoint
- You can set up additional Push API endpoints for developing and testing purposes. This can be done without impacting the current Push API V1.0 settings. Meaning that the Push API V1.0 messages are sent in parallel to messages that are sent by Push API V2.0. When you complete the testing and development cycle, delete/migrate the Push API V1.0 endpoints.
See What's New in AppsFlyer.
Push API Field tables
Fields removed from Push API V1.0
V1.0 Removed field |
V2.0 Replacement field |
Description |
---|---|---|
fb_adgroup_name | af_ad | |
fb_adgroup_id | af_ad_id | |
fb_adset_name | af_adset | |
fb_adset_id | af_adset_id | |
fb_campaign_id | af_c_id | |
fb_campaign_name | campaign | |
event_type | event_name |
Can be one of the following: |
attribution_type | media_source |
In V1.0 the attribution_type field had a value of organic or regular. Use the media_source field to derive the type of attribution as follows:
|
click_time | attributed_touch_time | |
cost_per_install | af_cost_value | |
device_brand (Android only) |
device_type |
Device_type contains both brand and model |
device_model (Android only) | device_type |
Device_type contains both brand and model |
Renamed fields
V1.0 name |
V2.0 name |
---|---|
agency | af_prt |
af_click_lookback | af_attribution_lookback |
re_targeting_conversion_type | retargeting_conversion_type |
appsflyer_device_id | appsflyer_id |
currency | af_cost_currency |
click_time_selected_timezone | attributed_touch_time_selected_timezone |
click_url | original_url |
download_time | device_download_time |
Fields added to Push API V2.0
Display name | V2.0 name | Description |
---|---|---|
Amazon Fire ID | amazon_aid | Amazon Fire TV advertising ID |
Contributor 1 Campaign | contributor_1_campaign | Campaign of the contributor |
Contributor 1 Match Type | contributor_1_match_type | Possible values include: gp_referrer, id_matching, SRN, download_time |
Contributor 1 Media Source | contributor_1_media_source | Media Source of the contributor |
Contributor 1 Partner | contributor_1_af_prt | Agency or PMD: always converted to lowercase |
Contributor 1 Touch Time | contributor_1_touch_time | Time of the touch |
Contributor 1 Touch Type | contributor_1_touch_type | Type of the touch click, impression, TV |
Contributor 2 Campaign | contributor_2_campaign | Campaign of the contributor |
Contributor 2 Match Type | contributor_2_match_type | Possible values include: gp_referrer/id_matching/srn |
Contributor 2 Media Source | contributor_2_media_source | Media Source of the contributor |
Contributor 2 Partner | contributor_2_af_prt | Agency or PMD |
Contributor 2 Touch Time | contributor_2_touch_time | Time of the touch |
Contributor 2 Touch Type | contributor_2_touch_type | Type of the touch (could be click/impression/TV) |
Contributor 3 Campaign | contributor_3_campaign | Campaign of the contributor |
Contributor 3 Match Type | contributor_3_match_type | Possible values include: gp_referrer/id_matching/srn |
Contributor 3 Media Source | contributor_3_media_source | Media source of the contributor |
Contributor 3 Partner | contributor_3_af_prt | Agency or PMD |
Contributor 3 Touch Time | contributor_3_touch_time | Time of the touch |
Contributor 3 Touch Type | contributor_3_touch_type | Type of the touch (could be click / impression / TV) |
Custom Data | custom_data | Data that is sent using the SDK See Android and iOS SDK guides |
Device Category | device_category | Possible values include: phone, tablet, other Compatible with Android SDK V4.8.8 and later |
DMA | dma | Designated Market Area - regions are the geographic areas in the US where local television viewing is measured by the Nielsen company. |
Event Revenue USD | event_revenue_usd | The amount of revenue in USD or in preferred currency, configurable under App Settings. |
Event Revenue | event_revenue | Amount of revenue using the Event Revenue Currency |
Event Revenue Currency | event_revenue_currency | The event revenue currency as reported to the SDK |
Event Source | event_source | The source of the event - either SDK or S2S |
Google Play Click Time | gp_click_time | Time of app page load in Google Play after an ad click. Time source: Google API Available from Android SDK version 4.8.5 Use case example: By comparing install_time to gp_click_time you can gain an insight as to how long it takes users from the time they begin to download the app until they open the app. |
Google Play Install Begin Time | gp_install_begin | Time that installation begins Time source: User device. Meaning the time that displays on the device. Note: Available from Android SDK version 4.8.5 |
Google Play Referrer | gp_referrer | The referrer URL of the installed package. Available from Android SDK version 4.8.5 |
GP Broadcast Referrer | gp_broadcast_referrer | Google Play Broadcast Referrer |
Install App Store | install_app_store | Identifies the Android store where the app was downloaded from (details) |
Is Primary Attribution | is_primary_attribution | During a re-engagement window, we can attribute to either the original media source (prior to the re-engagement) or to the re-engagement media source. While the event is within the re-engagement window, the original media source will not be the primary attribution. Outside of the re-engagement window, it will be the primary attribution. |
Is Receipt Validated | is_receipt_validated | true/false/null when implemented in the SDK, empty otherwise |
Keyword Match Type | keyword_match_type | The keyword match type returns by search networks APIs or attribution links shall be mapped to the raw report. Note: Google AdWords and Apple Search Ads are the only networks that return this parameter for search campaigns. |
Match Type | match_type | Attribution method type. Possible values include: gp_referrer (Google Play referrer string) id_matching probabilistic_modeling srn (Self-Reporting Network) tv (TV attribution) preinstall |
Network Account ID | network_account_id | Advertiser's account ID with the partner |
Postal Code | postal_code | Based on IP of the SDK |
Reengagement Window | af_reengagement_window | The re-engagement attribution window is the time period during which an event can be attributed to a retargeting campaign Limitation: The field is not populated in retargeting campaigns. |
Region | region | Based on IP fro the SDK |
State | state | Based on IP from the SDK |
Sub Site ID | af_sub_siteid | Sub-publisher ID |
User Agent | user_agent | The user agent for the URL |
Unique Push API fields
Display name | V2.0 name | Remarks |
---|---|---|
Selected currency | selected_currency | |
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 |