Track server-to-server events

The server-to-server (S2S) events API lets Adjust track your events via HTTP requests.

Here are the following types of requests that are accepted for S2S events:
  • GET with URL parameters
  • POST with URL parameters (no body)
  • POST with body parameters as Content-Type application/x-www-form-urlencoded

In this article, you'll learn how to set up and troubleshoot S2S event tracking.

Before you begin

Here’s what you need to know before getting started:

Requirements

  • A server to track events and send calls to Adjust

Helpful information

  • Installs, reattribution, and sessions are automatically recorded with the SDK, and cannot be sent to Adjust S2S. To prevent receiving large amounts of duplicate data, avoid sending similar activities (for example, "app open") using S2S, as Adjust does not deduplicate S2S events.

Send events to Adjust

To send events to Adjust, always pass the following parameters to https://s2s.adjust.com/event

ParameterDescriptionExample
idfa; gps_adid; etc.   Platform dependent advertising ID (see full list)

idfa=D2CADB5F-410F-4963-AC0C-2A78534BDF1E

gps_adid=660e1d86-6796-463a-be86-897993136018

event_tokenAdjust event token from the dashboardevent_token=f0ob4r
app_tokenAdjust app token from the dashboardapp_token=4w565xzmb54d
s2ss2s parameter set to 1s2s=1

Recommended additional parameters for event submission

For accurate event attribution, we recommend including the following parameters with your events.

ID typeParameter + exampleUsed for
Adjust device IDadidIdentifying LAT users on iOS without idfa information
IP addressip_addressEvent linking to third-parties (for example, Google) & including location-related information (for example, city, postal_code) in your callbacks. The ip_address parameter only accepts IPv4.nIPv6 is not yet supported.
created_at_unix
(recommended)

or

created_at
created_at_unix=1484085154

or

created_at=2017-01-02T15:04:05.000+0000

Telling us the exact moment an event occurred. This helps Adjust to provide precise reporting for your events.

 

Conditions for the created_at timestamp

The ‘created at’ timestamp can be specified using either the created_at_unix parameter or the created_at parameter.

  • You are recommended to use the created_at_unix parameter, as it only accepts numeric values and not floating-point values or non-numeric characters, to include decimal points (.). Timestamps with non-numeric characters are rejected. This reduces the chance of formatting or encoding issues. The created_at_unix parameter only accepts two time formats:

    Seconds - created_at_unix=1484085154
    Milliseconds - created_at_unix=1484085154000

  • If you use the created_at parameter, always encode the value. For example, 2017-01-02T15:04:05.000+0000 becomes 2017-01-02T15%3A04%3A05.000%2B0000
  • If your server-side event calls don’t contain a 'created at' timestamp, or if it isn't formatted correctly (for example, no timezone), Adjust sets the created_at time to our ReceivedAt timestamp.
  • All S2S events that include a ‘created at’ timestamp must be submitted chronologically for each device and for each event token, according to the ‘created at’ timestamp. For example, you must send a day-3 event before a day-7 event for the same device using the same event token. Otherwise, Adjust will reject the day-3 event. 
    • Make sure events are submitted within 28 days, as older activities are rejected.
  • All S2S events that include revenue and a ‘created at’ timestamp must be submitted chronologically, for each device and for all revenue event tokens, according to the ‘created at’ timestamp.  For example, you must send a day-3 revenue event on revenue event token X before a day-7 revenue event on revenue event token Y, for the same device. Otherwise, we will reject the day-3 revenue event.

Accepted device identifiers

The device identifiers accepted for S2S events are as follows:

Preferred identifiers
Raw IDFA (IOS only)idfa
Raw Google advertising IDgps_adid
Raw Amazon Fire advertising IDfire_adid
Open Advertising ID (OAID, Huawei only)oaid
Backup identifiers
Raw IDFA                                                        idfa
Raw IDFVidfv
Android IDandroid_id

Note: The Adjust device ID (adid) is preferred for passing as a backup identifier when possible. You must pass the adid for the S2S request to function. 

Share custom data

Pass custom event data to Adjust within S2S events using callback and partner parameters. Callback parameters return via raw data export, while partner parameters are shared with your network partners. Set up callback and partner parameters for S2S events using the following instructions: 

Track server-to-server events

To receive callback parameters for events tracked S2S, pass the JSON object through the callback_params parameter. The following is an example of two custom parameters, unencoded for demonstration:

{"f0o":"bar","bar":"baz"}

Here's an example of a JSON object passed with callback_params appended and properly encoded:

https://s2s.adjust.com/event?s2s=1&event_token=f0ob4r&app_token=4w565xzmb54d&idfa=8A3CB124-5A79-4334-8802-F75FEC099C58&callback_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D

To send partner parameters for events tracked server-to-server, pass them as a JSON object in the partner_params parameter. The following is an example of two custom parameters, unencoded for demonstration:

partner_params={"f0o":"bar","bar":"baz"}

Here’s an example S2S request with partner_params appended and properly encoded:

https://s2s.adjust.com/event?s2s=1&event_token=f0ob4r&app_token=4w565xzmb54d&idfa=8A3CB124-5A79-4334-8802-F75FEC099C58&partner_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D


The JSON object should only contain strings and should not be nested. If the parameters are incorrectly formatted, you’ll then receive an error message from Adjust.

Track revenue events

To track S2S revenue events, add the following revenue parameters to your event submissions:

 
ParameterDescription
revenue

Revenue event value in full currency units
(149.99 = $149.99). We accept a minimum
value of 0.001 for this parameter.

currencyRevenue event currency code
environmentEnvironment to post the data to
(environment=sandbox or
environment=production).
If this parameter is not included,
the event will be pushed to the
production environment.
 

Setup completion

Example S2S GET request with URL parameters / POST request with URL parameters and no body:

https://s2s.adjust.com/event?s2s=1&event_token=f0ob4r&app_token=4w565xzmb54d&idfa=D2CADB5F-410F-4963-AC0C-2A78534BDF1E&created_at=2017-01-02T15%3A04%3A05Z%2B0200&callback_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D&partner_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D

Example S2S POST request with parameters in body:

Request URL:
https://s2s.adjust.com/event
Body:
s2s=1&event_token=f0ob4r&app_token=4w565xzmb54d&idfa=D2CADB5F-410F-4963-AC0C-2A78534BDF1E&created_at=2017-01-02T15%3A04%3A05Z%2B0200&callback_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D&partner_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D

Event submission responses

All successfully tracked events return an OK response.

Failed events return an HTTP error code and JSON message, like this: {"error": "Event request failed ( {error message})"}

Error messages define the request problem. Use this table to identify your error, then review your setup or reach out to support@adjust.com for help.

Error codeError messageReason
400Bad event stateCan occur for various reasons. E.g., ‘created at’ time is before 'installed_at' time.

Check the response for additional details.

400Invalid app tokenApp token not set correctly
400Ignoring event, earlier unique event trackedA unique event was already tracked. This is ignored as a duplicate.
400Invalid callback parametersCallback parameters could not be extracted
400Invalid event tokenEvent token does not exist, was set incorrectly, or does not match the app token.
400Invalid revenueAmount set incorrectly or value too high (limit = 100,000,000,000) 
401Failed to authorize requestAuthorization token missing or does not match
403App is inactiveApp was deactivated in the dashboard
403Tracking disabledTracking not enabled for this platform
403Event token blacklistedEvent token blacklisted
404App token not foundApp token not found
404Device not foundNo device data found
413Request size too largeYour request exceeds our limit of 1 MB
451Device is opted outDevice is opted out 
500Internal error, contact support@adjust.comInternal error when updating device data

On this topic