Server-to-Server Events API

Introduction

The purpose of this API is to allow you to send events which occur outside the mobile app, directly to the AppsFlyer server. 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.

Method: POST

Header - "authentication"= {dev-key}

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

{
"appsflyer_id": {This is a mandatory field, AppsFlyer Device ID must be used },  // e.g. 1415211453000-6513894 
"idfa":{idfa},
"customer_user_id": {customer_user_id}, // Customer User ID optional parameter 
"bundle_id":{bundle_id},
"eventName": {The event name}, // e.g. "af_purchase"
"eventValue": {A JSON containing a rich in-app event value}, // e.g "{\"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}, // e.g  "2014-05-15 12:17:00.000"
"af_events_api" :"true"
}

{
"appsflyer_id": {This is a mandatory field, "AppsFlyer Device id" must be used },  // 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}, // e.g "{\"af_revenue\":\"6\" ,\"af_content_id\":\"15854\"}"
"eventCurrency": {Event currency}, // e.g "USD"
"ip": {device IP},
"eventTime": {Event timestamp in UTC}, // 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.

Requirements

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.
eventValue can be with an empty value, i.e., "eventValue":"", (no space is needed)
IP address (ip) should be the IP of the mobile device (during the event occurrence)
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.

Timing the Events

Server-to-server events can be sent in real time or in batch mode.

Note

When using S2S, you cannot send events directly from a JavaScript. You must create a local server, to send the request to AppsFlyer.

You can use the optional eventTime parameter to specify the time of the event occurrence (in UTC 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")

In batch mode, for events to be recorded with their real time stamps, they must all be sent to AppsFlyer by 02:00 AM (UTC) of the following day.

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.

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

Example 1

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

Example 2

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 was sent to the AppsFlyer server and not the time that the event occurred (4 May @ 09:00).

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.

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.

1. From the mobile device using AppsFlyer's SDK API (Android / iOS)

2. Via the Pull or Push API (click on link for more information about Push API or Pull API)

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

Testing Server-to-Server Events

1. Uninstall your app from your test device

2. Prepare a custom tracking link for testing S2S messages. The link should include the "s2s_test" media source name (&pid=s2s_test)

3. Send the link to your test device and click it

4. Install the app and launch it
You should now have a fresh install with the latest app version.

5. Fetch the new AppsFlyer Device ID to use on your test messages

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

from requests import requests
url =  "https://api2.appsflyer.com/inappevent/<APP_ID>" # i.e. com.appsflyer.sampleapp

payload = """
  {\r\n\t\"appsflyer_id\": \"<APPS_FLYER_ID>\",
  \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-07-08 4:17:00.000\",
  \r\n\t\"af_events_api\" :\"true\"\r\n}
"""
headers = {
 "authentication": "<YOUR_DEV_KEY>",
 "Content-type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
# handle return code


/* 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 = "{\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-07-08 4:17:00.000\"," +
                        "\r\n\t\"af_events_api\" :\"true\"\r\n}";
            request.AddParameter("undefined", body, ParameterType.RequestBody);
            IRestResponse response = client.Execute(request);
            // handle response by reading response.StatusCode
            Console.WriteLine(response.Content);
        }
    }
}

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.

Troubleshooting

I have created an S2S event but I cannot see it displayed in the dashboard.

Verify the endpoint used to send the event is correct and that the syntax of the body 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.
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.

Prev Tab:

Next Tab:

Introduction

Note

Note

Requirements

Timing the Events

Note

Note

Service Return Codes

Request Body Example

Fetching the AppsFlyer Device ID

Tip

Testing Server-to-Server Events

Troubleshooting

Articles in this section

Related articles