Server-to-server events API for mobile (S2S-mobile)

Payload parameters consist of:

• One or more device identifiers (depending on the operating system).
  • You may be unable to send the identifier for a good reason. For example, because the user has limited ad tracking (LAT). 
  • Failing to send an advertising ID/device identifier can cause attribution failure,  meaning that AppsFlyer can't attribute the event to the media source.
    • 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 attribution consequences of not doing so. 

curl --location --request POST 'https://api2.appsflyer.com/inappevent/<app_id_placeholder>' \
--header 'authentication: <dev_key_placeholder>
' \
--header 'Content-Type: application/json' \
--data-raw '{
  "appsflyer_id": "9999999999999-9999999999999999999",
	"advertising_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
	"customer_user_id" : "example_customer_id_123",
	"ip": "199.0.2.1",
	"af_events_api" :"true",
	"app_version_name" : "example_version_name",
	"eventTime" : "2020-02-25 12:00.000",
	"eventName": "af_purchase",
	"eventCurrency": "ZAR",
	"eventValue": 
	"{
		\"af_revenue\": \"1006\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }"
}
'

Consider: 

• For testing, use the AppsFlyer ID of a non-organic install so that test event attributes in realtime. Organic events attribute with a delay of a few hours.
• Some event fields are populated using the install attribution event of the user. For example, install time and media source. 

To attribute the test device as a non-organic install:

1. Prepare a custom attribution link for testing S2S messages. Set the media source parameter on the link as to s2s_test. Example: &pid=s2s_test 
2. Whitelist the test device
3. Uninstall the app from the test device.
4. Send the link to the test device.
5. Click on the link.
6. Install and then launch the app.
7. In the dashboard, check to see that the install is attributed.
8. Fetch the AppsFlyer ID to use in your S2S message.

To send the S2S test message:

1. Prepare an S2S message using the AppsFlyer ID allocated. See the following for code examples.
2. Send the message.
3. Do one of the following to see how the message is recorded in AppsFlyer:
   • Download the in-app events raw data report. Allow up to 15 minutes after sending the event for it to show up in the raw data report. 
   • Push API (Consider using tools like Postman and Webhook site.)
4. Check and view that:
   • Values sent in the S2S message correctly populate the report. Pay special attention to the Event date, Event currency, Event revenue, and Event value fields.
   • The attribution source and install time are populated by AppsFlyer.
   • Values provided by the SDK itself like SDK version are not populated.

• The advertising ID/device identifier is mandatory to assure postbacks to SRNs like Facebook and Google Ads. If you are unable to send the ID, take into consideration that postbacks can't be sent.
• If you send only the AppsFlyer ID, in-app events will be recorded and attributed correctly.

When AppsFlyer processes S2S in-app events, attribution fields are populated by using the AppsFlyer ID to identify the associated install event that preceded 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.

Backend logic is required to obtain values to populate parameter. The following describes how you can get the AppsFlyer ID:

• The AppsFlyer ID is mandatory and is used to attribute events.
• It is generated when a user first installs the mobile app.
• So that you can map your CUID to the AppsFlyer ID, you need to set the CUID in the app. 

To make it easier for you to know which user performed which event, implement the flow that follows:

• Set customer user ID when the user installs the app.
• AppsFlyer raw data reports contain the CUID and AppsFlyer ID. Use one of the data delivery tools to get this or AppsFlyer Push API. 
• Use the raw data reports to match the CUID with the AppsFlyer ID. 
• The AppsFlyer ID is available in the SDK integrated into your app (Android/iOS).
• Map AppsFlyer ID to customer user ID in your internal systems (important for future use).

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

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

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 attributed media source. You can get the ID using one of the following methods:

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

Events having a negative revenue value can be sent. For example, if a purchase was canceled. The parameter af_revenue can have negative values to record this. 

If you populate af_quantity, you might want to populate it with a negative value depending on your system logic. AppsFlyer doesn't make use of af_quantity.

Example with negative revenue

{
	"eventName": "cancel_purchase",
	"eventValue": 
	"{
		\"af_revenue\": \"-6\",
		\"af_content_type\": \"wallets\",
		\"af_content_id\": \"15854\",
		\"af_quantity\" :\"1\"
   }",
	"eventCurrency": "USD",
	
}

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, optimization and audience creation purposes.

• Endpoint: Verify that the endpoint used is correct.
• Verify that the payload contains the mandatory parameters. See here.
• Ensure that the AppsFlyer ID you are using to fire the event is a real appsflyer_id and is actually installed on the specific app. Not a test ID provided in the documentation. See here.
• S2S events don't support multi-events in one S2S request. Each event must be sent as a separate event. 
• In the overview dashboard, the date range relates to the app install date (LTV) and not to the event date.
  • Make sure you select the correct date range.
  • Make sure that the dashboard date range corresponds to the install date of the device (appsflyer_id) and not the date of the event.
• Event raw data reports: the date range relates to the event date and not the install date. 

If you send S2S events but their revenue is not recorded: ensure that the JSON that you send is stringified. The most important part is the event value parameter in the JSON. It must be stringified as shown in the example that follows.

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

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

Revenue values must not be formatted in any way. They can contain a decimal comma but this is not obligatory. Don't include currency signs or codes nor , delimiters. The revenue can be prefixed by a -

• Example valid values are: 123, -123.45, 123.456 
• Example Illegal values: 1,234.56, 1,234

Raw data fields are populated using the value sent in the S2S call and some fields are populated using the install event.  Similar behavior but not identical is observed for in-app events reported using the AppsFlyer SDK. There are some differences, specifically, the following fields are not populated for S2S events:

• WIFI
• Operator
• Language
• Device Type
• Device Category
• App Version: You can use app_version_name
• App Name