Skip to main content

Push API streaming raw data

John Smith

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

Push API V2.0

Push API streams raw data events generated by ZendeskConnect and 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 (ZendeskConnect or SKAN) as described in the sections that follow. 

ZendeskConnect 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 ZendeskConnect platform. This is typically within minutes. 
Message contents (fields)
  • Messages have a key:value structure.
  • See ZendeskConnect attribution Push API fields available.
  • Each key represents a raw data field. See description of raw data fields in ZendeskConnect. 
  • 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. 
Message types available

 

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 V2.0 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 ZendeskConnect
    • 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 ZendeskConnect
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

PushAPI-2_en-us.png

Set up Push API endpoints

 Caution

Don't use Push API for sending 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.

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

Push API setup checklist
Step No.  ZendeskConnect 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 ZendeskConnect attribution, plan the endpoint settings using the Push API planning checklist.

Not applicable
3

Set up ZendeskConnect 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 endpoints:
    • ZendeskConnect attribution: 6 endpoints. Each endpoint must be unique per app.
    • SKAdNetwork attribution: 1 endpoint. The endpoint can be different or the same as an ZendeskConnect attribution endpoint. 
Endpoint return code On receipt of a message, the endpoint must return an HTTP 200 status code.
Allowlist ZendeskConnect servers

Allowlist ZendeskConnect 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 ZendeskConnect attribution

  • Use that checklist to plan your ZendeskConnect 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 ZendeskConnect attribution endpoint

  • Only the admin can make changes to API settings. Team members can view Push API settings.
ZendeskConnectAdmin_us-en.png To add an ZendeskConnect 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 ZendeskConnect 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 ZendeskConnect IP addresses. 
    Note! A timeout mechanism, having a 3-second duration, is used. If ZendeskConnect doesn't get an OK message during this time ZendeskConnect 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 admin can make changes to API settings. Team members can view Push API settings.

ZendeskConnectAdmin_us-en.png To add a SKAdNetwork Push API SKAdNetwork 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 one SKAdNetwork endpoint 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 ZendeskConnect 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 admin can make changes to API settings. Team members can view Push API settings.

ZendeskConnectAdmin_us-en.png 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 admin can make changes to API settings. Team members can view Push API settings.

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

Troubleshooting, traits, and limitations

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 ZendeskConnect 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 ZendeskConnect support; include the app ID, endpoint URL, and a screenshot of the error message.

Traits and limitations

Traits
Trait 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. To get historical data use Pull API. 
Team member access Team members can view Push API settings but can't make changes.

Comments

0 comments

Article is closed for comments.

Powered by Zendesk