Push API streaming raw data

Premium
For:
Marketers Developers
Last update:

At a glance: Stream raw data attribution events to your server-side endpoints.

6970_Push_API_image.png

Related reading: Comparing raw data delivery tools | Set up the Push API using an API

Push API

Push API streams raw data generated by AppsFlyer attribution and SKAdNetwork (SKAN) attribution as messages to your servers. You can select the message types and content and set the destination endpoints.

The message types available, data freshness, and fields depend on the attribution framework (AppsFlyer or SKAN) as described in the sections that follow. 

AppsFlyer attribution messages

Message characteristics

Characteristic Details
Message type segregation
  • Messages can be segregated by endpoint (maximum 6 endpoints per app) or you can determine the message type by examining the value of the fields listed:
    • event_name
    • conversion_type
    • campaign_type 
  • The values of the fields, per message type, are indicated in the table that follows.

Example:

A message contains the following:

  • conversion_type=install
  • campaign_type=organic
  • event_name=install

Use the table to determine that this event is the install event of an organic user. 
Data freshness

Messages are sent soon after the event is recorded on the AppsFlyer platform. This is typically within minutes. 
Message contents (fields)
  • Messages have a key:value structure.
  • See AppsFlyer attribution Push API fields available.
  • Each key represents a raw data field. See description of raw data fields in AppsFlyer. 
  • Blank or null keys aren't sent at all.
  • The example contains both null and empty fields. Real postbacks have neither empty nor null fields. The example provided has a JSON format.
Format of timestamp fields
  • UTC timestamps: yyyy-mm-dd hh:mm:ss.sss. For example, displays as2019-09-17 00:09:00.123. An event took place at 18:00 Tokyo time. The event time is converted to UTC, which is 09:00. The time recorded is the UTC time. 
  • Selected time zone (app-specific) timestamps: yyyy-mm-dd hh:mm:ss.sss±th:tm. For example 2019-09-17 18:00:16.000+0900. An event took place at 18:00 Tokyo time. The event time shown is recorded as 18:00+09:00. 09:00 is the Tokyo time zone. 

Available message types

 

Attribution

context

Message type

 conversion_type field

campaign_type field

event_name field
User acquisition Install* install

Non-organic: UA

Organic: organic

install
User acquisition  Install in-app events install

Non-organic: UA

Organic: organic

Advertiser-defined event names

Retargeting

 Re-engagement re-engagement retargeting re-engagement
Retargeting  Re-engagement in-app events re-engagement retargeting Advertiser-defined event names
Retargeting  Re-attribution  reinstall retargeting re-attribution
User acquisition  Reinstall reinstall

Non-organic: UA

Organic: organic

reinstall
Retargeting Re-attribution in-app events reinstall retargeting Advertiser-defined event names
* Some installs relating to view-through attribution are attributed to the restricted media source.

Unique fields

Display name Push API name
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
* This is the app-level setting in force at the time the API message is sent.

SKAN attribution messages

This section describes the messages (report types) available for SKAN and how to identify the messages. Read this section, then Set up SKAN attribution endpoint.

Related reading: SKAN raw data fields. Push API messages have the equivalent structure and fields. 

Message characteristics:

Characteristic Details
Message type segregation
  • All messages are sent to 1 endpoint set by you.
  • To determine the message type, use the following fields:
    • event_name
    • skad_redownload
  • The values of the fields, per message type, are indicated in the table that follows

Example:

A message contains the following:

  • event_name: af_skad_install
  • skad_redownload: true

Because skad_redownload: true, you determine that this is a redownload event. 
Data freshness
  • Installs, redownloads, and in-app events:
    • Processed daily
    • Sent to your endpoint on the day following receipt of the iOS postback by AppsFlyer
    • Expect to receive event messages 05:00–08:00 UTC (exact times fluctuate)
    • Example: Postbacks received on Monday are sent starting Tuesday 05:00 UTC
  • Postbacks from iOS and Postbacks copy: Messages are sent soon after they arrive in AppsFlyer
Message examples The spreadsheet contains message examples. The example provided has a JSON format. SKAN example messages.

Message types for SKAN attribution

Message type 

event_name field

skad_redownload field
Installs  af_skad_install
  • Possible values: false, blank, null. 
  • If the field is not in the message, regard the value as false. 
Re-downloads  af_skad_install True
In-app events 

The name of the event set by the advertiser

 The name of the event set by the advertiser
Postbacks from iOS

Never available in this message

 Sometimes available
Postbacks copy

Never available in this message

 Sometimes available


Determine the SKAN attribution message type

Note: This doesn't apply to postbacks copy messages, that arrive directly from iOS.

PushAPI-2_en-us.png

Set up Push API endpoints

 Caution

Don't use Push API for sending AppsFlyer-attributed data to third parties for the following reasons:

  • You can breach 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. Make sure that you comply with the media source's terms of use.
    For example, Twitter, Snapchat, Pinterest.

Note:  This caution doesn't apply to SKAN data. Use Push API to send SKAN data to third-party endpoints.

To set up Push API, complete the following action list.

Push API setup checklist

Step No.  AppsFlyer attribution SKAdNetwork attribution 
1

If you already have an active Push API endpoint, you can skip this step. 

Complete the server-side requirements.
2

For AppsFlyer attribution, plan the endpoint settings using the Push API planning checklist.

Not applicable
3

Set up AppsFlyer attribution endpoint

Set up SKAdNetwork attribution endpoint

Server-side requirements (your server)

Ensure that your server complies with the following requirements: 

Server-side requirements

Endpoint URL
  • Valid domain name
  • Maximum number of unique endpoints per app: 
    • AppsFlyer: 6 endpoints
    • SKAdNetwork: 3 endpoints
Endpoint return code On receipt of a message, your 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 for AppsFlyer attribution

  • Use that checklist to plan your AppsFlyer attribution endpoint settings. The numbers in the figure match the row numbers in the checklist.
  • This section isn't relevant to SKAdNetwork attribution. See Set up SKAdNetwork attribution. 

Endpoint 

PushAPI_us-en.png

Endpoint planning table

No.

Setting

 Details Use this column to record your planned settings
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 preselected by default.
  • We don't 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, new in-app events are added automatically. 
  • You can only select an in-app event after it has been recorded at least once. If necessary, use S2S to fire the event.
  • mceclip1.png
  

Set up AppsFlyer attribution endpoint

Note: Only the AppsFlyer account owner can make changes to Push API settings. Other account users can view the settings.

To add an AppsFlyer attribution endpoint:
  1. Go to Integration > API Access. Scroll down to the Push API section.
  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 until 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 common fields are preselected by default. You can cancel the selections.
      • 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.

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 you have allowlisted AppsFlyer IP addresses. 
    Note! A timeout mechanism, having a 2-second duration, is used. If AppsFlyer doesn't get an OK message during this time AppsFlyer regards this as a message send failure. 
  2. Verify that your endpoint received the test message.
    View a copy of the message sent. 

Set up SKAdNetwork attribution endpoint

Note: Only the AppsFlyer account owner can make changes to Push API settings. Other account users can view the settings.

To add a SKAdNetwork Push API endpoint:
  1. Go to Integration > API Access. Scroll down to the Push API section.
  2. Select SKAdNetwork as the attributing entity. 
  3. Click Add Endpoint. 
    Note    : You can define 1-3 SKAdNetwork endpoints per app. 
  4. Select an HTTP method: POST or GET
  5. Enter the Endpoint URL. If you get the message this URL is not safe, contact AppsFlyer support.
  6. We don't send null/empty fields and the associated key. Take this into account when planning your import/parsing processes.
  7. Click Save.
    The Push API is now active. Data is sent to the endpoint. 

Additional procedures—managing endpoints

Change an endpoint

Note: Only the AppsFlyer account owner can make changes to Push API settings. Other account users can view the settings.

To modify endpoint settings: 

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

Delete an endpoint

Note: Only the AppsFlyer account owner can make changes to Push API settings. Other account users can view the settings.

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, traits, and limitations

Test message 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 events if you have enabled both:

  • Install in-app events
  • Retargeting in-app events 

Identify and deduplicate in-app events

 

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

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.

Specifications and limitations

Specification Remarks 
Ad networks Not available 
Agencies Not available
App-specific time zone Supported
App-specific currency  Supported
Size limitations Not applicable
Organic  Yes
Non-organic Yes
Data freshness Continuous 
Historical data Not supported. If you are missing data, use Pull API to get the data. In the case of SKAN, you can get some historical data via Data Locker (limited by the Data Locker availability window). 

Account owner/user access

Only the AppsFlyer account owner can make changes to Push API settings.

  • Each AppsFlyer account has only one account owner. This is the first AppsFlyer user (created at the time the account was opened).

Other account users can view Push API settings but can't make changes.