The Swrve Events API is a series of REST calls for sending event data to Swrve from your app.

API calls – API key and user ID

Swrve authenticates all API calls to *api.swrve.com using either your app API key or Identity key.

All calls to the Swrve Events APIs (and to the Swrve A/B Test APIs) require a unique user identifier. For server-side integrations, it is the responsibility of the developer integrating Swrve into the app to ensure they supply a unique user identifier. Otherwise, the Swrve SDK generates a random unique user ID for each new user.  Swrve relies upon this uniqueness property to monitor DAU counts, New User counts, and funnel progression.

If you’re supplying your own user ID, consider the following:

• If you want to track your users across multiple devices, platforms, and channels, use an account ID specific to your application. For more information about using your own external user ID with the Event API, see the following section. Note: The external ID must be a non-discoverable key that identifies your user across multiple channels and platforms. Emails or other personally identifiable information (PIIs) are not accepted as external user IDs, they will be rejected on the server side.
• For developers on the Facebook platform, a good user ID is a simple hash of the user’s Facebook ID (for example, md5($facebook_id);).
• A unique device ID works for Android, but it is no longer accepted in new apps in Apple’s app store.
• If you are developing on the iOS platform, ensure that the unique user ID you are using is consistent with your other providers and partners. In particular, you should note that Apple has deprecated the UDID. Swrve recommends using ID for Vendors where possible.
• Apple Game Center ID is another option for game users on iOS, but the requirement to use Game Center can lead to user drop-off.

API calls – external user ID

As noted above, Swrve’s Event API supports using your own external user ID to identify your users when sending event or user updates. To use this functionality, you must also generate an Identity-specific API key on your app’s Integration Settings screen that you then send with the external user ID when making the API call. The Identity key must remain secret—do not use the Identity key in your SDK integration or expose it to end users. For more information about how to use the Identify API in your SDK integration, see the relevant integration guide:

• Android
• iOS
• Unity
• Roku
• Smart TV
• Web

To send updates to the Event API with an external user ID, use the Event API as normal, but instead of providing a session_token or <user_id> and <api_key> pair as parameters, provide the following:

• external_user_id – The external user ID.
• identity_secret_key – The Identity secret key.

Error codes

If an error occurs while processing a request that references an external user ID, you might receive one or more of the following error codes.

Application version

Swrve tracks the current application version with each user, which enables you to create segments based on the version of the application that your users are using. As a result, you can easily track how quickly your users are upgrading from version to version. Swrve also enables you to create A/B tests that target specific application versions. You must ensure that you are sending the application version parameter with every message to ensure that these A/B tests function correctly.

Nearly all API calls to Swrve expect an app_version parameter, including all calls to *api.swrve.com. The value of this parameter should be a string that represents the version of the application that the user is currently using. Typically, this should be the same build version that you submit to your platform’s app-store. For example, you might use the Bundle Version on iOS, or Build.VERSION.RELEASE on Android.

This parameter is optional, but strongly recommended. In future versions of the API, this parameter will become mandatory.

Event payload

You can include event payloads (swrve_payload) with every REST call to *api.swrve.com. This parameter is optional. For more information on event payloads, see the Swrve Events API Payloads Guide.

This associated payload should be a JSON object of name/value pairs. It is restricted to containing string or integers, and any values that use quotes (") need to have the quotes escaped (") to prevent errors in the QA device events log. For event payload examples, see the Session Start and Purchase Events sections.

UTF-8 encoding

We recommend that you UTF-8 encode POST bodies.

Session start

Send this API call to Swrve when a user connects to the app. Pair this with a session_end event when the user disconnects.

Request method

POST or GET

URL

Using your app ID in the above URL endpoint enables Swrve to extend proper resources to each individual dashboard. For example: https://123.api.swrve.com/1/session_start.

Example of opening a user session

curl -d "api_key=<api_key>" -d "user=<user_id>" 
-d "swrve_payload=
{"optional_key":"optional_value","paid":false}
" 
https://<app_id>.api.swrve.com/1/session_start

curl -d "api_key=<api_key>" -d "user=<user_id>" 
-d "swrve_payload=
{"optional_key":"optional_value","paid":false}
"  
https://<app_id>.eu-api.swrve.com/1/session_start

URL parameters

Error codes

If an error occurs while processing the request, you might receive one or more of the following error codes and need to make sure your integration is equipped to handle error conditions.

Session end

Send this API call to Swrve when a user disconnects from the app. Pair this with a session_start event when the user connects. If no session_end event is received for a session end, the session is automatically timed out (timeout occurs after one hour). In this instance, the session length is defined as the time from the session start event to the last event received.

Request method

POST or GET

URL

Example of closing a user session

curl -d "api_key=<api_key>" 
-d "user=<user_id>" 
https://<app_id>.api.swrve.com/1/session_end

curl -d "api_key=<api_key>" 
-d "user=<user_id>" 
https://<app_id>.eu-api.swrve.com/1/session_end

URL parameters

Error codes

See Session Start.

Events

Swrve enables developers to send in-app events for later analysis. An event is represented as a single string.

Request method

POST or GET

URL

Example of sending an event

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "name=winning" 
https://<app_id>.api.swrve.com/1/event

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "name=winning" 
https://<app_id>.eu-api.swrve.com/1/event

URL parameters

Error codes

See Session Start.

Update user list content

Send a Swrve.user_tag_update event with the following parameters to add or remove users from a Swrve user list.

Request method

POST

Example

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "name=Swrve.user_tag_update"
-d "swrve_payload={"action":"add","tag_name":"list_1"}"
https://<app_id>.api.swrve.com/1/event

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "name=Swrve.user_tag_update"
-d "swrve_payload={"action":"add","tag_name":"list_1"}" 
https://<app_id>.eu-api.swrve.com/1/event

URL parameters

Error codes

See Session Start.

Purchase

Send this API call to Swrve when a user purchases an in-app item.

Request method

POST or GET

URL

Example of a purchase event

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "item=hammer_17"-d "currency=coins" 
-d "quantity=2" -d "cost=100" -d 
https://<app_id>.api.swrve.com/1/purchase

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "item=hammer_17"-d "currency=coins" 
-d "quantity=2" -d "cost=100" -d 
https://<app_id>.eu-api.swrve.com/1/purchase

Example of a purchase event with payload

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "item=shield_2" -d "currency=gems" 
-d "quantity=1" -d "cost=5" -d "swrve_payload={"level":1}" –d 
https://<app_id>.api.swrve.com/1/purchase

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "item=shield_2" -d "currency=gems" 
-d "quantity=1" -d "cost=5" -d "swrve_payload={"level":1}" –d 
https://<app_id>.eu-api.swrve.com/1/purchase

URL parameters

Error codes

See Session Start.

IAP

The IAP API call notifies Swrve that a user has made a real money transaction. This call is most commonly invoked from the app server’s handler for a post-back message that comes from a payment provider. When a payment is successful, the payment provider usually posts a message to the app server to notify the app that the payment was successful. This same data can then be sent to Swrve to notify Swrve that the user has spent money.

Request method

POST

Content type

application/json

URL

Examples

Notify Swrve that a user has traded $10 USD for 1,000 coins:

curl -H "Content-Type:application/json" 
-d "{"api_key": "<api_key>", "user":"<user_id>", "product_id"
:"com.coinpack.1", "cost":"0.99", "local_currency"
:"USD", "rewards": { "coins"  { "type"
: "currency" , "amount" : "1000" } } , "quantity"
:"1" , "app_store":"unknown_store" } "
https://<app_id>.api.swrve.com/1/iap

curl -H "Content-Type:application/json" 
-d "{"api_key": "<api_key>", "user":"<user_id>", "product_id"
:"com.coinpack.1", "cost":"0.99", "local_currency"
:"USD", "rewards": { "coins"  { "type"
: "currency" , "amount" : "1000" } } , "quantity"
:"1" , "app_store":"unknown_store" } "
https://<app_id>.eu-api.swrve.com/1/iap

Notify Swrve that a user has purchased a Gold VIP membership bundle:

curl -H "Content-Type:application/json" -d "{"api_key"
: "<api_key>", "user":"<user_id>", "product_id"
:"com.VIP.bundle.gold", "cost":"10.99", "local_currency"
:"USD", "rewards": { "avatar" : {"type": "item", "amount" 
: "1" }, "diamonds" : { "type": "currency" , "amount" 
: "1000" } } , "quantity":"1" , "app_store":"unknown_store" }" 
https://<app_id>.api.swrve.com/1/iap

curl -H "Content-Type:application/json" -d "{"api_key"
: "<api_key>", "user":"<user_id>", "product_id"
:"com.VIP.bundle.gold", "cost":"10.99", "local_currency"
:"USD", "rewards": { "avatar" : {"type": "item", "amount" 
: "1" }, "diamonds" : { "type": "currency" , "amount" 
: "1000" } } , "quantity":"1" , "app_store":"unknown_store" }" 
https://<app_id>.eu-api.swrve.com/1/iap

URL parameters

{
<name of reward>:
  {
  "type"  : "item" | "currency",
  "amount" : <number of items or amount of currency >
  },
...
}

Error codes

See Session Start.

Currency given

This API call enables apps to notify Swrve that a user has been gifted virtual currency by the app itself.

Request method

GET or POST

URL

Example

Notify Swrve that the current user has been given 1,000 coins:

curl -d "api_key=<api_key>" -d "user=<user_id>" 
-d "given_currency=coins" -d "given_amount=1000" 
https://<app_id>.api.swrve.com/1/currency_given

curl -d "api_key=<api_key>" -d "user=<user_id>" 
-d "given_currency=coins" -d "given_amount=1000" 
https://<app_id>.eu-api.swrve.com/1/currency_given

URL parameters

Error codes

See Session Start.

Currency given and IAP events

You should ensure that currency given amounts are not also being tracked by means of the IAP event, as this would result in double-counting of the currency given to users in your app. Any currency given to users that is not accompanied by some type of revenue generation (whether direct or alternative revenue), should be tracked only through the given_currency event.

User

This API call enables apps to notify Swrve of changes to a user’s properties. These changes can form the basis of segments and dimension graphs displayed in the Swrve service. User update messages are also treated as regular event messages and are displayed on the Events screen and can be part of funnels and so forth. The name of the event is Swrve.user_properties_changed.

The Segments screen provides an overview of your user base by segment, such as age, gender, and location. To avail of this functionality, you must set the age, gender, and location fields for your users.

Sometimes, your app might need to update the attributes of a user when that user may not be using the app. An example of this would be where the app server sets a referral code on a set of users as a nightly process. Since the user has not actively initiated these events, the events should not necessarily contribute to certain performance indicators, such as a count of the Daily Active Users (DAU) or the Monthly Active Users (MAU). To handle these cases, you can set an optional parameter user_initiated to the value false. If this parameter is present and has the value false, then this user update event does not count towards these metrics.

Request method

GET or POST

URL

Examples

Set the user’s level attribute to 7:

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "level=7" 
https://<app_id>.api.swrve.com/1/user

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "level=7" 
https://<app_id>.eu-api.swrve.com/1/user

Set the user’s age, gender, and location attributes:

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "age=24" 
-d "gender=male" -d "location=Ireland" 
https://<app_id>.api.swrve.com/1/user

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "age=24" 
-d "gender=male" -d "location=Ireland" 
https://<app_id>.eu-api.swrve.com/1/user

Update the referral code of a user without affecting DAU and MAU:

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "Swrve.referrer_id=my_advertising_partner.campaign_name" 
-d "user_initiated=false" https://<app_id>.api.swrve.com/1/user

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "Swrve.referrer_id=my_advertising_partner.campaign_name" 
-d "user_initiated=false" https://<app_id>.eu-api.swrve.com/1/user

Update a DateTime user property (for example, hotel check out time):

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "checked_out=2016-03-11T09:29:33.915Z" 
https://<app_id>.api.swrve.com/1/user

curl -d "api_key=<api_key>" 
-d "user=<user_id>" -d "checked_out=2016-03-11T09:29:33.915Z" 
https://<app_id>.eu-api.swrve.com/1/user

URL parameters

Error codes

See Session Start.

Batch

This API call enables apps to notify Swrve of a vector of events, for a single user. The use case for this API is sending events in bulk from mobile apps clients. The Swrve iOS and Unity SDKs in particular use this batch API.

Important notes:

• This API requires that the HTTP content-type be set to application/json.
• local_cost and local_currency parameters must be included for IAP events sent using the Batch API (they are optional for the non-Batch API). For IAP events sent using the batch API, the cost parameter is replaced with local_cost.
• The order of events received through the batch API is based on their order in the batch rather than the time attribute of the data.
• The time of an event in the Swrve system is determined by the system time rather than the timestamp of the data. However the difference between time attributes in successive events is used when calculating session duration and associated metrics.
• The user_initiated parameter is supported for batch events of the following types: user_update, iap, and event.
• The attributes field is required for user update events, even when no attributes are being sent.
• If you have virtual currencies in your app, you must also add them on the App Settings screen (exactly as they’ve been configured in the app, for example, case-sensitive, spaces), or any events referencing the incorrect or missing currencies will be ignored and return an error event called Swrve.error.invalid_currency. For information on adding virtual currencies, see Add your app.
• For more information about the Session Token, see Session Token.

Request method

POST

URL

Example

Notify Swrve of a series of events for a user:

curl
 -H "Content-Type:application/json"
 -d "{
   "user":"user_id",
   "version":"2",
   "app_version":"1.00",
   "session_token":"<session token>",
   "data":[
     {"type":"session_start", "time":1327211960781},
     {"type":"purchase",      "time":1327312660341,"item":"item_name","currency"
     :"gold","cost":"100","quantity":"1"},
     {"type":"currency_given","time":1327332452053,"given_currency"
     :"gold","given_amount":"100.0"},
     {"type":"event",         "time":1327440860341,"name"
     :"event.name","payload":{"key":"value"}},
     {"type":"user",          "time":1327441035690,"attributes"
     :{"balance":1200,"level":12,"experience":101}},
     {"type":"session_end",   "time":1327611741945}
   ]
 }"
 https://<app_id>.api.swrve.com/1/batch

curl
 -H "Content-Type:application/json"
 -d "{
   "user":"user_id",
   "version":"2",
   "app_version":"1.00",
   "session_token":"<session token>",
   "data":[
     {"type":"session_start", "time":1327211960781},
     {"type":"purchase",      "time":1327312660341,"item":"item_name","currency"
     :"gold","cost":"100","quantity":"1"},
     {"type":"currency_given","time":1327332452053,"given_currency"
     :"gold","given_amount":"100.0"},
     {"type":"event",         "time":1327440860341,"name"
     :"event.name","payload":{"key":"value"}},
     {"type":"user",          "time":1327441035690,"attributes"
     :{"balance":1200,"level":12,"experience":101}},
     {"type":"session_end",   "time":1327611741945}
   ]
 }"
 https://<app_id>.eu-api.swrve.com/1/batch

URL parameters

Error codes

See Session Start.

Batch API events and session count KPIs

For events sent via the batch API, there are some additional considerations used when calculating session metrics. Additional data from the client (the time that the event happened according to the client) is used for calculating the length of sessions. However, the client timestamp is not used for determining the time at which the session happened. This is because the time on client devices tends to be, in a small number of cases, incorrect (and in many cases can be out by a number of years). So, if Swrve gets the following batch of events at 2:00 pm on July 8, it attributes the session as a six-minute session that happened at 2:00 pm.

[ 
   session_start at 1:53 pm July 8; 
   named_event at 1:55 pm July 8; 
   session_end at 1:59 pm July 8 
]

For this reason, we recommend you send session_start and then send the current batch of events.

Multi-user batch

This API call enables apps to notify Swrve of a vector of events, for one or more users. The use case for this API is sending events in bulk across multiple users, as distinct from the Batch events API, which sends multiple events for a single user.

Important notes:

• See notes for Batch API.

Request method

POST

URL

Example

Notify Swrve of a series of events for a user:

curl
 -H "Content-Type:application/json"
 -d "{
   "version":"3",
   "api_key":"<api_key>",
   "data":[
 	{"user":"user1","type":"session_start","time":1327211960781},
 	{"user":"user2","type":"purchase","time":1327312660341,
     "item":"item_name","currency":"gold","cost":"100","quantity":"1"},
 	{"user":"user3","type":"currency_given","time":1327332452053,
     "given_currency":"gold","given_amount":"100.0"},
 	{"user":"user1","type":"event","time":1327440860341,"name"
 	:"event.name","payload":{"key":"value"}},
 	{"user":"user1","type":"user","time":1327441035690,"attributes"
 	:{"balance":1200,"level":12,"experience":101}}
   ]
}"
 https://<app_id>.api.swrve.com/1/multi_user_batch

curl
 -H "Content-Type:application/json"
 -d "{
   "version":"3",
   "api_key":"<api_key>",
   "data":[
 	{"user":"user1","type":"session_start","time":1327211960781},
 	{"user":"user2","type":"purchase","time":1327312660341,
     "item":"item_name","currency":"gold","cost":"100","quantity":"1"},
 	{"user":"user3","type":"currency_given","time":1327332452053,
     "given_currency":"gold","given_amount":"100.0"},
 	{"user":"user1","type":"event","time":1327440860341,"name"
 	:"event.name","payload":{"key":"value"}},
 	{"user":"user1","type":"user","time":1327441035690,"attributes"
 	:{"balance":1200,"level":12,"experience":101}}
   ]
}"
 https://<app_id>.eu-api.swrve.com/1/multi_user_batch

URL parameters

Error codes

See Session Start.

Output parameters

{ "nonexistent_external_user_ids": [ "userid_1", "userid_2" ] }