Swaarm's S2S solution allows app developers to send events that they track in their backend applications to enhance the quality and security of the data collected through attribution by the Swaarm SDK. While every event can be sent through the S2S API, we encourage developers to send the ones that can only be tracked in the backend or where the probability of fraud is high.
Security
In order to guarantee the authenticity of the client calling the API, an S2S token should be sent for each request.
There are two allowed methods:
via Authorization header as shown in the example below
Authorization: s2sTokenForTheStoreApp
via the s2s_token parameter as show below
https://track.yourdomain.swaarm-app.com/postback?s2s_token=s2sTokenForTheStoreApp
The token can be generated under the corresponding Store App under the Token tab.
Sending Events
The events API has two mandatory parameters:
user_id: the id of the user that performed the event (called App User Id in Swaarm)
✏️ Note:
On iOS, this is the IDFV
On Android, its the AppSetId
On the Web, its the Swaarm.identifier() in the JS SDK
event_id: the event being performed by the user, as defined on the App > Events page under Mapping Id
The following parameters are optional but highly encouraged:
ip_address: the IP of the user
user_agent: the User-agent of the user
The following parameters are optional:
sale_amount: defined the amount of revenue that was generated by this event
sale_amount_currency: the currency of the sale amount
aggregated_event_value: a numeric value that can be aggregated in reports (e.g. number of coins)
event_value: any additional data that should be saved in relation to this event, can be in a format of your choosing, we recommend json
The HTTP call can be either POST or GET. A couple examples for the same are listed below:
GET https://track.yourdomain.swaarm-app.com/postback?s2s_token=s2sTokenForTheStoreApp&user_id=0000-AAAA-BBBB-CCCC&event_id=register
POST https://track.yourdomain.swaarm-app.com/postback?user_id=0000-AAAA-BBBB-CCCC&event_id=purchase&sale_amout=42
Authorization: s2sTokenForTheStoreApp
Following are the Response codes that are available:
200 - the event was registered correctly
400 - the http call is missing either the user_id or the event_id
401 - the s2s token is invalid
404 - the endpoint being called is incorrect
Attribution
While attribution on the Web is possible using only S2S events, it is discouraged due to the amount of complexity that comes with a correct implementation that tracks across all channels. You should use the Web SDK instead whenever possible.
The simplest method to do attribution using S2S events is to send the events to the s2sevent endpoint after choosing a unique identifier for the user you are sending events to:
https://track.yourdomain.swaarm-app.com/s2sevent?token=INSERT_TOKEN&user_id=INSERT_USER_ID&event_id=&user_ip=INSERT_IP&user_ua=INSER_USER_AGENT
The call will perform the attribution using the same process as the mobile SDKs. Please note that the ip and user agent are mandatory parameters in every S2S call.
Events can then be sent to the same endpoint, by using the event_id parameter. Here is the format of the call:
https://track.yourdomain.swaarm-app.com/s2sevent?event_id=registration&token=INSERT_TOKEN&user_id=INSERT_USER_ID&event_id=&user_ip=INSERT_IP&user_ua=INSER_USER_AGENT
To ensure that the sessions are tracked properly and the active user derived metrics are correctly configured make sure you send an__open event whenever a new session is created in you app (e.g. when the mobile app is opened, or for web when a login is performed). Format for open event:
https://track.yourdomain.swaarm-app.com/s2sevent?event_id=__open&token=INSERT_TOKEN&user_id=INSERT_USER_ID&event_id=&user_ip=INSERT_IP&user_ua=INSER_USER_AGENT
Attribution Advanced
To emulate the attribution process done through the Web SDK, the following steps can be done:
Collect the click id, this can be done by checking the query parameter
clkidand:If it exists, collect it and move to step 2.
If it does not exists, fire a GET request to the url:
https://track.yourdomain.swaarm-app.com/click?no_redirect=true&user_ip=INSERT_IP_OF_USER&user_ua=INSERT_USER_AGENT_OF_USER&s2stoken=INSERT_YOUR_TOKEN. The response is a JSON object with a single property,id. Save this id as your click id.
Save the click id together with your session data
When the user navigates to the conversion page, you can fire a GET request to:
https://track.yourdomain.swaarm-app.com/postback?s2s_token=s2sTokenForTheStoreAppSave the click id from step 1 in your internal database and use it in every event call in the future in the
user_idparameter
This process, although more advanced, makes the collection of data before attribution more precise, allowing extra parameters to be collected before attribution is performed.