Server-to-server events API

Introduction

This API allows you to send events that either happen outside the app or happen in the app but are not sent through the AppsFlyer SDK. For example, if you have both a web and mobile interface, you can record all events from both mediums in AppsFlyer.

Note

The Content-Type must be set as application/json.

URL:https://api2.appsflyer.com/inappevent/{app_id}

Android example:https://api2.appsflyer.com/inappevent/com.appsflyer.myapp

iOS example: https://api2.appsflyer.com/inappevent/id123456789

It is important to pay extra attention that the App ID on iOS contains the leading "id" before the ID, otherwise the request ends with HTTPS 200 OK, but the event is not registered.

Important!

The maximum size of the JSON payload should not exceed 1K.

The JSON payload must be passed as a string and the event value must be stringified.

Make sure that the JSON payload includes the parameter "af_events_api" :"true"
This parameter ensures that the event is structured as a rich event to enable automatic mapping of the event values to various partners.

See examples below.

Method: POST

Header - "authentication"= {dev-key}

The dev key is found in Dashboard >> App Settings >> Dev Key

{
  "appsflyer_id": {AppsFlyer Device ID }, // e.g. 1415211453000-6513894
  "idfa":{idfa},
  "customer_user_id": {customer_user_id}, // Customer User ID optional parameter
  "eventName": {The event name}, // e.g. "af_purchase"
  "eventValue": {A JSON containing a rich in-app event value - must be stringfied},
  "{

    \"af_revenue\":\"6\",
    \"af_content_type\":\"wallets\",
    \"af_content_id\":\"15854\"

  }",
  "eventCurrency": {Event currency}, // e.g "USD"
  "ip": {device IP},
  "eventTime": {Event timestamp in UTC +0}, // e.g "2014-05-15 12:17:00.000"
  "af_events_api" :"true"
}

{
	"appsflyer_id": {AppsFlyer Device id}, // e.g. 1415211453000-6513894 
	"advertising_id": {advertising_id},
	"customer_user_id": {customer_user_id}, // Customer User ID optional parameter ---
	"eventName": {The event name}, // e.g "af_purchase
	"eventValue": {A JSON containing a rich in-app event value - must be stringified} 
	"{	
		\"af_revenue\":\"6\",
		\"af_content_type\":\"wallets\",
		\"af_content_id\":\"15854\"
	}"

	"eventCurrency": {Event currency}, // e.g "USD"
	"ip": {device IP},
	"eventTime": {Event timestamp in UTC +0}, // e.g "2014-05-15 12:17:00.000"
	"af_events_api" :"true"
}

Note

All Reserved Character (https://tools.ietf.org/html/rfc3986#section-2.1) must be percent-encoded before the URI is formed.

Parameters

Mandatory parameters: appsflyer_id (AppsFlyer Device id), eventName, eventValue and af_events_api
Highly recommended parameters: idfa for iOS and advertising_id for Android.
If you wish to map your in-app events from organic users with external partners, these parameters are MANDATORY. Also, some features like Audiences rely on device ID to segment your users and update the networks.
Optional - eventValue can be with an empty value, i.e., "eventValue":"", (no space is needed)
Optional - IP address (ip) should be the IP of the mobile device (during the event occurrence)
Optional - The customer user ID field (customer_user_id) is a user identifier parameter, mapped to the Customer User ID field in the Raw Reports. The Customer User ID SDK API attaches this value automatically to all SDK originated in-app events. Make sure to include this field will ALL your S2S events to enjoy the same functionality.

Preparing data for parameters

Backend logic is required in order to obtain certain values for the parameters mentioned above. Below you can find the recommended flow for obtaining these values:

Mapping AppsFlyer ID with customer user ID

AppsFlyer ID is a mandatory parameter when sending server to server in-app events. To make it easier for you to know which user performed which event, implement the flow below:

Set customer user ID when the user installs the app
Download raw data report for installs through export data or pull API
Get AppsFlyer ID by matching the customer user ID in your internal systems with the customer user ID in the raw data report.
Note: you can get the AppsFlyer ID of your users from the AppsFlyer SDK integrated in your apps (Android / iOS)
Map AppsFlyer ID to customer user ID in your internal (important for future use)

Once you map AppsFlyer ID with your internal customer user ID, you can easily know which user performed which event. You can then obtain the AppsFlyer ID and other values (event value, event currency, event time etc.) and send the server to server in-app event.

Timing the events

Server-to-server events can be sent in real time or with an event time stamp.

You can use the optional eventTime parameter to specify the time of the event occurrence (in UTC +0 timezone). If the parameter is not included in the message, AppsFlyer uses the timestamp from the HTTPS message received.

eventTime format is: "yyyy-MM-dd HH:mm:ss.SSS" (e.g. "2014-05-15 12:17:00.000")

When sending events with timestamps, for these events to be recorded with their real-time stamps (when they actually took place), they must all be sent to AppsFlyer by 02:00 AM UTC +0 of the following day.

Events with past timestamps, which are not sent by 2:00 AM, are recorded under the time that they are sent.

Event with timestamp sent before 2 am utc +0

Event Triggered: 2 May @ 22:00

Event Sent to AppsFlyer's servers: 3 May @ 01:00

Event is recorded in AppsFlyer's platform under the real time that the event occurred (2 May @ 22:00).

Event with timestamp sent after 2 am utc +0

Event Triggered: 2 May @ 22:00

Event Sent to AppsFlyer's servers: 4 May @ 09:00

Event is recorded in AppsFlyer's platform at the time it is sent to the AppsFlyer server and not the time that the event occurred (4 May @ 09:00).

Event with future timestamps

Events sent with future timestamps are always recorded in AppsFlyer under the time they are sent to AppsFlyer, and not the event timestamp in the payload.

Timing events: visual timeline

Note

The maximum number of S2S requests is 60K per minute or 1K per second. Contact your Customer Success Manager if your requirements are different.

Service return codes

200: OK when the request has been processed by the AppsFlyer system.
401: unauthorized when the key provided in the authentication header is not the dev-key for this app.
400: Bad request when the request failed at least one of the validation criteria
500: Internal server error this indicates a server error

If your servers are protected by a firewall you will need to white list the incoming responses from AWS IP address Ranges to receive the return messages.

Request body example

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "af_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000",
	"af_events_api" :"true"
}

In this case, AppsFlyer receives an S2S in-app event which represents a purchase event with revenue, as well as additional properties such as content type etc.

Special cases

Sending negative revenue

If you want to send an event with negative revenue (for events such as cancelled purchase or refund), you can specify negative value in the revenue parameter. For example:

{
  "appsflyer_id": "1415211453000-6513894",
	"advertising_id": "38412345-8cf0-aa78-b23e-10b96e40000d",
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	"ip": "1.2.3.4",
	"eventTime": "2014-05-15 12:17:00.000",
	"af_events_api" :"true"
}

Sending events without event value

If you want to send events without event value, simply pass an empty string to event value: "event_value":""

AppsFlyer is then able, according to the advertiser's configuration, to send such rich in-app events to media sources for advanced targeting, optimisation and audience creation purposes.

Fetching the AppsFlyer device ID

appsflyer_id is a mandatory parameter in server-to-server event messages. AppsFlyer uses this parameter to attribute the event to the original device and to the attributed media source.

There are several ways of obtaining this ID.

From the mobile device using AppsFlyer's SDK API (Android / iOS)
Via the Pull or Push API (click on link for more information about Push API or Pull API)
Export the raw data installation report

Tip

When testing S2S messages, if you're using raw data or push or pull APIs, look for the record with media source "s2s_test". This is your test device and its AppsFlyer Device ID is the ID you need.

Difference between organic and non-organic

When you send S2S in-app events, AppsFlyer automatically associates additional data with the events. The additional data comes from the install event that precedes the in-app events.

What this means is that some data that AppsFlyer associates with non-organic S2S in-app events, is not associated with organic S2S in-app events.

Example

For example, if you compare raw data reports of non-organic and organic S2S in-app events, non-organic events contain data that organic in-app events do not.

Non-organic in-app events contain data about the media source, campaign, attributed touch type and attributed touch time.

Organic in-app events, on the other hand, follow an organic install. Organic install do not have data related to campaign, media sources or attributed touch type and time.

Testing server-to-server events

Uninstall your app from your test device
Prepare a custom attribution link for testing S2S messages. The link should include the "s2s_test" media source name (&pid=s2s_test)
Send the link to your test device and click it
Install the app and launch it
You should now have a fresh install with the latest app version.
Fetch the new AppsFlyer Device ID to use on your test messages
Send S2S messages with the new AppsFlyer device ID. See below for code examples:

/* using the okhttp package 
install from maven https://mvnrepository.com/artifact/com.squareup.okhttp3/okhttp */
import okhttp3.*;
import java.io.IOException;

public class SendRequest {
  public static void main(String[] args) {

    OkHttpClient client = new OkHttpClient();
    MediaType mediaType = MediaType.parse("application/json");

    RequestBody body = RequestBody.create(mediaType, "" +
        "{\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
        "\r\n\t\"customer_user_id\": \"123456\",\r\n\t\"eventName\": \"af_purchase\",\r\n\t\"" +
        "eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\",\r\n\t\"" +
        "eventCurrency\": \"USD\",\r\n\t\"" +
        "eventTime\": \"2018-08-10 4:17:00.000\",\r\n\t\"" +
        "af_events_api\" :\"true\"\r\n}");

    Request request = new Request.Builder()
        .url("https://api2.appsflyer.com/inappevent/<APP_ID>")
        .post(body)
        .addHeader("Content-Type", "application/json")
        .addHeader("authentication", "<YOUR_DEV_KEY>")
        .build();

    try {
      Response response = client.newCall(request).execute();
      System.out.println(response.code());
      System.out.println(response.body().string());
    } catch (IOException e) {
      e.printStackTrace();
    }
  }
}

''' using the requests python package, install using pip install requests '''

import requests
import json

url = "https://api2.appsflyer.com/inappevent/<APP_ID>" # i.e. com.appsflyer.sampleapp
payload = {
		"appsflyer_id": "<APPS_FLYER_ID>",
		"eventName": "af_purchase",
		"eventValue": "{\"af_revenue\":\"7\" ,\"af_content_type\":\"wallets\"}",
		"eventCurrency": "USD",
		"ip": "1.0.0.0",
		"eventTime": "2018-09-02 15:17:00.000",
		"af_events_api" :"true"
	}


headers = {
	"authentication": "<YOUR_DEV_KEY>",
	'Content-Type': 'application/json' 
}

res = requests.request("POST", url, headers=headers, json=payload)
print(res)
print(res.text)

/* using the request npm package, install using npm install request */
var request = require("request");

var options = { method: 'POST',
 url: 'https://api2.appsflyer.com/inappevent/<APP_ID>',
 headers: 
  { 
   "authentication": '<YOUR_DEV_KEY>',
   'Content-Type': 'application/json' 
  },
 body: 
  { appsflyer_id: '<APPS_FLYER_ID>',
   customer_user_id: '123456',
   eventName: 'node_js',
   eventValue: '{"node_js":"6" ,"af_content_id":"15854"}',
   eventCurrency: 'USD',
   ip: '1.0.0.0',
   eventTime: '2018-07-09 4:17:00.000',
   af_events_api: 'true' },
 json: true };

request(options, function (error, response, body) {
 if (error) throw new Error(error);

 console.log(body);
});

/* using the RestSharp package, install using NuGet */
using System;
using RestSharp;
namespace CS
{
  class Event
  {
    static void Main(string[] args)
    {
      var client = new RestClient("https://api2.appsflyer.com/inappevent/<APP_ID>");
      var request = new RestRequest(Method.POST);
      request.AddHeader("authentication", "<YOUR_DEV_KEY>");
      request.AddHeader("Content-Type", "application/json");
      var body = "{\"appsflyer_id\": \"<APPS_FLYER_ID>\"," +
            "\"customer_user_id\": \"123456\"," +
            "\"eventName\": \"af_purchase\"," +
            "\"eventValue\": \"{\\\"af_revenue\\\":\\\"6\\\" ,\\\"af_content_id\\\":\\\"15854\\\"}\"," +
            "\"eventCurrency\": \"USD\"," +
            "\"eventTime\": \"2018-07-08 4:17:00.000\"," +
            "\"af_events_api\" :\"true\"}";
      request.AddParameter("undefined", body, ParameterType.RequestBody);
      IRestResponse response = client.Execute(request);
      // handle response by reading response.StatusCode
      Console.WriteLine(response.Content);
    }
  }
}

$purchase_event = array(
            'appsflyer_id' => <APPS_FLYER_DEVICE_ID>,
            'idfa' => <IDFA>,
            'eventCurrency' => <PURCHASE_CURRENCY>,
            'ip' => <DEVICE_ID_ADDRESS>,
            'eventTime' => date("Y-m-d H:i:s.000", time()),
            'af_events_api' => "true"
            );

$purchase_event['eventName'] = 'af_purchase';
$purchase_event['eventValue'] = json_encode(array('af_revenue' => <PURCHASE_REVENUE>,
                        'af_price' => <PURCHASE_PRICE>, 
                        'af_order_id' => <PURCHASE_ORDER_ID>, 
                        'af_currency' => <PURCHASE_CURRENCY>, 
                        'af_content_type' => <PURCHASE_TYPE>, 
                        'af_quantity' => <PURCHASE_QUANTITY>, 
                        'af_content' => <PRODUCT_NAME>, 
                        'af_content_id' => <PRODUCT_ID>)
                        );

$data_string = json_encode($purchase_event);                                          
        
$ch = curl_init('https://api2.appsflyer.com/inappevent/<YOUR_APP_ID>');                                   
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");  
curl_setopt($ch, CURLOPT_HEADER, true);                                 
curl_setopt($ch, CURLOPT_POSTFIELDS, $data_string);                                 
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);                                   
curl_setopt($ch, CURLOPT_HTTPHEADER, array(                                     
'Content-Type: application/json',
'authentication: <YOUR_APPS_FLYER_DEV_TOKEN>',                                    
'Content-Length: ' . strlen($data_string))
);                                                          
                                                          
$result = curl_exec($ch);

$curl = curl_init();

AppsFlyer Go script on Github

7. Download the in-app events raw data report.
Check your sent values under the "event_value" column. Allow up to 15 minutes after sending the event for it to show up in the raw data report.

Note

The raw data of server-to-server events does not include any values originated in the SDK, such as app name, OS version, app version etc.

Troubleshooting

S2S events are not appearing on the dashboard

Verify the endpoint used to send the event is correct and that the syntax of the payload is also correct. See here.
Check that the AppsFlyer ID you are using to fire the event is a real appsflyer_id which is actually installed on your specific app (not a test ID provided in the documentation). See here.
S2S events does not support sending events in bulk. It's not possible to send several events in bulk (single request with a single payload that contains the data for several events). Each event should be sent separately.
To see the event in the dashboard - make sure the date selected in the dashboard corresponds to the install date of that device (appsflyer_id) and not the date of the event.

To see the event in the Raw Data Report - you must select the date of the event and NOT the date of the install.

S2S events show no revenue

If you send S2S events but their revenue is not recorded, make sure that the JSON that you send is stringified. The most important part is the event value parameter in the JSON. It must be stringified i.e.

"{\"af_revenue\":\"6\" ,\"af_content_type\":\"wallets\"}"

If it is not stringified then the event value is not processed correctly and revenue cannot be recorded.

Important!

Do NOT format the revenue value in any way. It should not contain comma separators, currency sign, or text. A revenue event should be similar to 1234.56, for example.

Server errors and responses

Error Message	Response Code	How to Handle
Failed to Authenticate	400	Make sure you pass the correct dev key in the headers: "authentication": "<MY_DEV_KEY>".
appsflyer_id is a mandatory field	400	Make sure you pass the correct AppsFlyer ID in the JSON. Also make sure that the JSON is stringified and formatted correctly.
Payload is missing or failed to parse	400	Make sure that the JSON is stringified and formatted correctly. This error is also returned if more than one event is included in the JSON payload. Make sure to send one event per request.
Internal Server Error	500	Check the JSON that you pass as the payload. Make sure it is stringified

Introduction

Note

Important!

Note

Parameters

Preparing data for parameters

Mapping AppsFlyer ID with customer user ID

Timing the events

Event with timestamp sent before 2 am utc +0

Event with timestamp sent after 2 am utc +0

Event with future timestamps

Timing events: visual timeline

Note

Service return codes

Request body example

Special cases

Sending negative revenue

Sending events without event value

Fetching the AppsFlyer device ID

Tip

Difference between organic and non-organic

Example

Testing server-to-server events

Note

Troubleshooting

S2S events are not appearing on the dashboard

S2S events show no revenue

Important!

Server errors and responses

Articles in this section

Page Contents:

Server-to-server events API

Introduction

Note

Important!

Note

Parameters

Preparing data for parameters

Mapping AppsFlyer ID with customer user ID

Timing the events

Event with timestamp sent before 2 am utc +0

Event with timestamp sent after 2 am utc +0

Event with future timestamps

Timing events: visual timeline

Note

Service return codes

Request body example

Special cases

Sending negative revenue

Sending events without event value

Fetching the AppsFlyer device ID

Tip

Difference between organic and non-organic

Example

Testing server-to-server events

Note

Troubleshooting

S2S events are not appearing on the dashboard

S2S events show no revenue

Important!

Server errors and responses

Articles in this section

Related articles

Page Contents: