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.
Set up S2S authentication
To guarantee the security of your S2S events and protect against spoofed requests, set up S2S authentication. This requires each incoming request to carry a token generated in your Adjust dashboard. Requests that do not carry a valid token are rejected by our server.
To set up S2S authentication, follow these steps.
In the dashboard
- Find your app and select the app options caret (^)
- Select All Settings > S2S Security
- Select Create Token
- Enter a token name
- Select Create
- Select Copy (clipboard icon) and send the token to your developer to add to your S2S event requests
Once the authentication token is added to your S2S requests, run tests to confirm the integration. At this point, S2S authentication is not active and requests carrying invalid tokens are still accepted. Speak to your dedicated Technical Account Manager or contact support@adjust.com to validate the setup before activating S2S authentication.
Example POST request with token added:
curl -v -X POST -H "Authorization: Bearer v8s5opi0zs45607l8h8c48wak2vxb5oe" "https://s2s.adjust.com/event?s2s=1&app_token=abc123kuvada7&event_token=xyzklm&gps_adid=11110111-2345-6789-1122-000000005678"
Expected response:
> POST /event?s2s=1&app_token=abc123kuvada7&event_token=xyzklm&gps_adid=11110111-2345-6789-1122-000000005678 HTTP/1.1
> Host: s2s.adjust.com
> User-Agent: curl/7.54.0
> Accept: */*
> Authorization: Bearer v8s5opi0zs45607l8h8c48wak2vxb5oe
Requests return one of the responses below.
Response code | Response message | Reason |
---|---|---|
200 | OK | Request accepted |
202 | Missing authentication token | No token added to the request |
202 | Wrong authentication token | Token added but not recognized. Check it is set correctly and is active on the dashboard |
Activate S2S authentication
Only activate S2S authentication after you have tested your token implementation and had this validated by your Technical Account Manager or our team at support@adjust.com.
To activate S2S authentication, follow these steps.
- Find your app and select the app options caret (^)
- Select All Settings > S2S Security
- Select Activate S2S authentication
- Switch the toggle ON
- Confirm to proceed
Good job! Now, all incoming S2S requests are required to carry an active authentication token.
Manage your tokens
To add multiple auth tokens, follow the same setup steps listed above.
Note: Always test your tokens after implementation. When S2S authentication is active, requests with new tokens that are not correctly implemented are rejected.
To delete a token, select Delete (trash icon). This immediately removes the token from your dashboard view and authentication requirements. To recover a deleted token, select Recover (arrow icon).
If you delete your only valid auth token, Adjust automatically deactivates S2S authentication. This ensures you do not reject ALL S2S traffic.
Send events to Adjust
To send events to Adjust, always pass the following parameters to https://s2s.adjust.com/event
Parameter | Description | Example |
idfa; gps_adid; etc. | Platform dependent advertising ID (see full list) |
|
event_token | Adjust event token from the dashboard | event_token=f0ob4r |
app_token | Adjust app token from the dashboard | app_token=4w565xzmb54d |
s2s | s2s parameter set to 1 | s2s=1 |
Recommended additional parameters for event submission
For accurate event attribution, we recommend including the following parameters with your events.
ID type | Parameter + example | Used for |
Adjust device ID | adid | Identifying LAT users on iOS without idfa information |
IP address | ip_address | Event 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.
- 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
becomes2017-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 ourReceivedAt
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 58 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 ID | gps_adid |
Raw Amazon Fire advertising ID | fire_adid |
Open Advertising ID (OAID, Huawei only) | oaid |
Backup identifiers | |
---|---|
Raw IDFA | idfa |
Raw IDFV | idfv |
Android ID | android_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.
To receive callback parameters for events tracked server-to-server, pass them as a JSON object (properly escaped) through the callback_params
parameter. For partner parameters, use the partner_params
parameter.
Unencoded example: partner_params={"f0o":"bar","bar":"baz"}
Example S2S request with encoded partner parameters appended:
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, then you’ll receive an error from Adjust.
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:
Parameter | Description |
---|---|
revenue |
Revenue event value in full currency units |
currency | Revenue event currency code |
environment | Environment to post the data to ( environment=sandbox orenvironment=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 code | Error message | Reason |
400 | Bad event state | Can occur for various reasons. E.g., ‘created at’ time is before 'installed_at' time. Check the response for additional details. |
400 | Invalid app token | App token not set correctly |
400 | Ignoring event, earlier unique event tracked | A unique event was already tracked. This is ignored as a duplicate. |
400 | Invalid callback parameters | Callback parameters could not be extracted |
400 | Invalid event token | Event token does not exist, was set incorrectly, or does not match the app token. |
400 | Invalid revenue | Amount set incorrectly or value too high (limit = 100,000,000,000) |
401 | Failed to authorize request | Authorization token missing or does not match |
403 | App is inactive | App was deactivated in the dashboard |
403 | Tracking disabled | Tracking not enabled for this platform |
403 | Event token blacklisted | Event token blacklisted |
404 | App token not found | App token not found |
404 | Device not found | No device data found |
413 | Request size too large | Your request exceeds our limit of 1 MB |
451 | Device is opted out | Device is opted out |
500 | Internal error, contact support@adjust.com | Internal error when updating device data |