At a glance: Attribution event data is pushed to you in real-time for use in your IT systems. You select the attribution events and the data is sent to your web service endpoint.
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 no longer be updated and will be discontinued.
- 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
| Campaign type | Event type | Non-organic | Organic | Retargeting |
|---|---|---|---|---|
| User acquisition | Install | ✓ | ✓ | |
| User acquisition | Install in-app events | ✓ | ✓ | |
| Retargeting | Re-engagement | ✓ | ||
| Retargeting | Re-engagement in-app events | ✓ | ||
| Retargeting | Re-attribution | ✓ | ||
| Retargeting | Re-attribution in-app events | ✓ |
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 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.
Checklist
Complete this checklist before you setup Push API.
- 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:
- TLV 1.1
- TLV 1.2 cyphers supported
- 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. This 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.
Setting up Push API
To add a Push API endpoint:
- In AppsFlyer, go to Integration > API Access.
The API Access window opens. - Scroll down to the Push API section.
The Push API endpoint section displays.
- Click Add Postback.
You can configure up to 6 push API endpoints. - Select an HTTP method: POST or GET
- Enter the Postback URL.
- (Optional) Select Push API version: (default) 2.0
- Select one or more event types to be sent to the endpoint URL.
- Click Save
The Push API is now active
Conversion data is sent to the endpoint. - Test the endpoint using the procedure that follows.
- (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:
- Click Send Test.
A test result message displays below the Send Test button.
A test message is sent to the endpoint. - Check that the endpoint received the test message.
A copy of the message sent follows.
Test POST and GET API messages
At present, the message sent as a test message is the Push API V1.0 message. What's important, is that you receive the message and not the content.
Removing postbacks
To remove a Postback:
- Go to Integration > API Access.
Scroll down to the Push API access section. - Click Remove Postback.
- 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,2019-09-17 00:09:25.123 - For timestamp fields in selected time zone: format
yyyy-mm-dd hh:mm:ss.±th:tm. For example2019-01-20 04:51:16.000+0000
| 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 |
Up until Feb 3, 2020 an additional field, download_time_selected timezone is also available. |
| 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. |
| Deep Link URL | deeplink_url | Available from Q1-2020 |
| OAID | oaid | Available from Q1-2020 |
| Keyword ID | keyword_id | Available from Q1-2020 |
| Store Reinstall | store_reinstall | Available from Q1-2020 |
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 | Available from Q4/2019 |
| 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 | Available from Q4/2019 |
| user_agent | User Agent | |
| wifi | WIFI |
Troubleshooting, limitations & traits
Duplication of retargeting events
In some cases, retargeting events are duplicated. This occurs when an in-app purchase event takes place as a result of a retargeting campaign during the UA re-engagement window.
In this case, two attribution events are generated to attribute the revenue to the media source that brought the install and the media source that brought the re-engagement.
You will only get two Push API's if you have enabled Push APIs for both
- install in-app events
- retargeting in-app events
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 event is sent twice with the following details:
| Event type | Media source | is_retargeting | re_targeting conversion_type |
|---|---|---|---|
| Non-organic | ua_network | False | null (no value) |
| Retargeting | retar_network | True | re-engagement |
How do I identify duplicate retargeting events?
Use the is_primary_attribution boolean field which indicates the primary and secondary media sources as follows.
- In UA campaigns the value can only be true because the UA media source is the only media source.
- In retargeting campaigns:
- True: identifies the re-engagement media source
- False: identifies the original UA 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. 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
| 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.
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
- 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:
- Going forward field additions in Appsflyer will be made available rapidly in Push API 2.0. Push API V1.0 won't have field changes and we plan to deprecate this version.
- 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. Set up a new endpoint or migrate the existing 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 |
The event_name field which can have the following values:
|
| 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 |
device_type |
Device_type contains both brand and model |
| device_model | 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 Note: The V1.0 name is available until February 3, 2020. |
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 insite 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 fingerprinting 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 from 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 |
Up until Feb 3,2020 an additional field, download_time_selected timezone is also available. |
| 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 | |
| Deep Link URL | deeplink_url | Available from Q1-2020 |
| OAID | oaid | Available from Q1-2020 |
| Keyword ID | keyword_id | Available from Q4-2019 |
| Store Reinstall | store_reinstall (False=Download, True=Redownload) | Available from Q4-2019 |
Comments
Please sign in to leave a comment.