Server-to-server events API

At a glance: Use the Server-to-Server (S2S) events API to send events that occur outside of your app.  For example, if you have both a web and mobile interface, you can record events from the web interface using S2S and events from the mobile using the SDK.

Server-to-Server events need to be prepared as follows:

• Content-Type: Set as application/json.
• URL endpoint:

  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

    Note: The app ID is the app's itunes ID. Ensure that the App ID in iOS contains a leading id before the ID. Failure to do so results in a valid 200 OK return code but the event is not registered.
  • Windows example:

    https://api2.appsflyer.com/inappevent/a1b2c3d4e5f6

    Note: The app ID is the app's ID on Microsoft App Store.
• Maximum size of the JSON payload: 1K 
• The JSON payload must be passed as a string and the event value must be stringified.
• The JSON payload must include 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 the 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"
}

Parameters

• Prepare the API message using the parameters listed here. 
• Ensure that you send all the mandatory parameters and at least one advertising (device) parameter.
• You may be unable to send the advertising identifier for good reason. For example,  the user enabled limited ad tracking (LAT). 
• Failing to send an advertising ID/device identifier can cause attribution failure,  meaning that AppsFlyer can't attribute the event.
  • This occurs, for example, if the install record no longer exists due to data retention policies of integrated partners. 
  • The device identifier parameter is not mandatory, you can elect not to send any device identifier but take into consideration the consequences.
• If you timestamp events usingeventTime, the events must arrive at AppsFlyer before 02:00 UTC of the next day. Late arrivals are timestamped by AppsFlyer using the time of arrival. For example, if the event took place on Monday, it must arrive by no later than Tuesday 02:00 UTC. 

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:

1. Set customer user ID when the user installs the app
2. Download raw data report for installs through export data or pull API
3. 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)
4. 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.

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

{
  "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"
}

AppsFlyer is then able, according to the advertiser's configuration, to send such rich in-app events to media sources for advanced targeting, optimization 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. The ID can be obtained as follows:

• From the mobile device using AppsFlyer SDK API: Android, iOS
• From the AppsFlyer platform using one of the following: Pull API, Push API, Export raw data installation  

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.