Last modified September 6, 2021 by Shelly Wolfe

Swrve Events API

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.

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Select the relevant tab based on your app configuration. For more information, see How do I configure the Swrve SDK for EU data storage?

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.
The user ID used when sending events must be the same as the user ID used when querying A/B test and resource information.

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:

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.

Code Text Description
403 No such external ID The external user ID does not exist.
403 Invalid Secret Key Check that your Identity secret key is correct.
429 Alias resolution is at capacity, try again later The app is trying to perform too many alias resolutions or something is wrong on the Swrve server side. Try resending the request later and reducing the rate of requests.

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.

The Swrve iOS SDK uses the application’s bundle version automatically.

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

US

https://<app_id>.api.swrve.com/1/session_start

EU

https://<app_id>.eu-api.swrve.com/1/session_start

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

US

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

EU

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

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
app_version Optional The version of the application that the user is currently using.
swrve_payload Optional A JSON object of name-value pairs that are restricted to strings or integers.

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.

Code Text Description
400 Invalid Parameter The request included an invalid parameter or an invalid JSON object, based on the specification.
403 Invalid API Key Check that your API key is correct.
410 API key no longer valid The API key is not recognized, possibly due to the app having been removed from the system. Check that the API key and app ID are correct.
503 Service Unavailable An error occurred on the Swrve server side. Attempt to resend the events later, if possible.

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

US

https://<app_id>.api.swrve.com/1/session_end

EU

https://<app_id>.eu-api.swrve.com/1/session_end

Example of closing a user session

US

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

EU

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

URL parameters

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
app_version Optional The version of the application that the user is currently using.

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

US

https://<app_id>.api.swrve.com/1/event

EU

https://<app_id>.eu-api.swrve.com/1/event

Example of sending an event

US

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

EU

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

URL parameters

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
name Required The name of the event. This should be a string; for example app_started. The name can use dot notation to indicate a hierarchy. The name also must contain only letters, numbers, dashes, underscores, and dots. The first string of valid characters is taken as the event name. If the name level.start/ is supplied, it is interpreted as level.start.
app_version Optional The version of the application that the user is currently using.

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

US

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

EU

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

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
name Required To update the contents of a user list, this value must be Swrve.user_tag_update.
swrve_payload Required A JSON object of name-value pairs where the values are restricted to strings or integers. To add or remove a user from a list, you must include the following payload keys:

  • action –  The action you want to take to add or remove a user from the list. Possible values are add and remove.
  • tag_name – The List ID of the user list you want to update.

For information on how to create and find user list IDs, see User lists.

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

US

https://<app_id>.api.swrve.com/1/purchase

EU

https://<app_id>.eu-api.swrve.com/1/purchase

Example of a purchase event

US

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

EU

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

US

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

EU

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

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
item Required The ID of the item that has been purchased.
cost Required The integer amount of in-app currency spent on one item (see quantity).
quantity Optional (Default is 1) Used if a user has bought the same item multiple times in a single purchase. In this instance, the cost should be the cost of a single item, and Swrve performs the multiplication to account for the quantity.
currency Required The in-app currency that was used to buy the item. This will usually be something like gold or coins. This call produces an error if the currency supplied is not known to the Swrve system.
app_version Optional The version of the application that the user is currently using.
swrve_payload Optional A JSON object of name-value pairs where the values are restricted to strings or integers.

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.

To enable Swrve to verify a receipt against your app for greater precision during validation, you must input the Apple bundle ID into Swrve. To enable validation of Google Play IAP receipts, you must input the public key for licensing and in-app billing. For more information about configuring receipt validation for Apple and Google Play, see the platform-specific Integration guide.

Request method

POST

Content type

application/json

URL

US

https://<app_id>.api.swrve.com/1/iap

EU

https://<app_id>.eu-api.swrve.com/1/iap

Examples

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

US

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

EU

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:

US

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

EU

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

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
product_id Required for Google and unknown_store The SKU ID of the in-app purchase (also used as the item UID). For Apple, this is populated from the receipt and, for Google, this is populated from the receipt if a valid Google Play licensing public key is provided in the Swrve service.
cost Required The amount of real money that the user has spent. This value can be an integer or a floating point value.
quantity Required for unknown_store The number of IAP purchases as an integer; this multiplies the cost and rewards. For Apple, this is populated from the receipt. This value is always 1 for Google.
local_currency Required This parameter represents the currency that the user spent. The parameter should be specified as a 3-character string, from the ISO 4217 currency codes. For example, USD for US Dollars or EUR for Euro.
If this parameter is not specified, then it is substituted with a default value of USD. This default behavior is to allow seamless backward compatibility with older versions of the Swrve API. Swrve strongly recommendeds that you always specify a local_currency.
rewards Optional JSON object specifying one or more rewards:

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

Amount must be > 0.

If the reward is a currency, this call produces an error if the currency supplied is not known to Swrve.

app_store Required The possible values are apple, google or unknown_store.
receipt Required for Apple and Google A string for Apple that contains the base64 receipt string that is expected in the receipt-data parameter of iTunes’ IAP verification service. This is also a string for the Google receipt.
receipt_signature Required for Google The verifiable digital signature as a string.
app_version Optional The version of the application that the user is currently using.
transaction_id Required for Apple iOS7 receipts iOS7 introduced a change to IAP receipts; unlike iOS6 receipts, iOS7 receipts contain a list of previous transactions. Therefore, a transaction_id must be set for the IAP purchase for an iOS7 receipt. Send iOS6-style receipts in the receipt parameter as usual.
Any items in the rewards object are not reported on separately.

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

US

https://<app_id>.api.swrve.com/1/currency_given

EU

https://<app_id>.eu-api.swrve.com/1/currency_given

Example

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

US

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

EU

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

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID.
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
given_currency Required The name of the in-app currency that was given to the user who sent this event. This is typically string such as coins or hearts. This call fails and return an error (HTTP 400) in the following instances:

  • If the value given is the empty string (“”).
  • If the value given does not match (case-sensitive) one of the currencies listed on the App Settings screen in the Swrve service.
given_amount Required The amount of in-app currency that the user received. This value should be passed as an integer or floating-point numbers (such as 2 or 6.5). The value must be greater than zero. This call fails with an error (HTTP 400) in the following instances:

  • If the value is zero (0 or 0.0).
  • If the value is a negative number (-1 or -1.0).
  • If the value is the empty string (“”).
  • If the value does not parse as a double (for example, the string twelve).
app_version Optional The version of the application that the user is currently using.

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

US

https://<app_id>.api.swrve.com/1/user

EU

https://<app_id>.eu-api.swrve.com/1/user

Examples

Set the user’s level attribute to 7:

US

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

EU

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:

US

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

EU

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:

US

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

EU

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):

US

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

EU

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

Parameter Presence Description
user

external_user_id

Required Identifies the user the event relates to, whether using the Swrve-generated user ID or your own external user ID..
api_key

identity_secret_key

Required The API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you may use either the app API key or Identity key for authentication. However, if you’re using an external user ID, you must send the Identity key.
user_initiated Optional If this parameter is specified and has the value false then this event does not count towards some performance indicators, as described above. If this parameter has any other value, or if the parameter is not present or is not specified, then the event counts towards all performance indicators as normal.
property_name  Optional/Multiple allowed, must have at least one to have any effect. Contains the new value for this user’s field; for example level=5 or health=80.
app_version Optional The version of the application that the user is currently using.
DateTime Optional The date and time of the user property, in ISO8601 format:
YYYY-MM-DDTHH:MM:SS.000Z
You should convert the DateTime to UTC, otherwise it will not work as expected.

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 in user update events is not supported. If you are uploading user properties to Swrve you should not send them via the batch API, instead send the user properties with the user update 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

US

https://<app_id>.api.swrve.com/1/batch

EU

https://<app_id>.eu-api.swrve.com/1/batch

Example

Notify Swrve of a series of events for a user:

US

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

EU

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

Parameter Presence Description
N/A Required A JSON POST body containing the fields user, version, app_version, session_token, data, where:

  • user is the user id of the user for this list of events.
  • version is currently the number 2.
  • app_version is the version of the application in question.
  • session_token is as described in the session token section above.
  • data is an array of events of the format.

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:

Request method

POST

URL

US

https://<app_id>.api.swrve.com/1/multi_user_batch

EU

https://<app_id>.eu-api.swrve.com/1/multi_user_batch

Example

Notify Swrve of a series of events for a user:

US

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

EU

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

Parameter Presence Description
N/A Required A JSON POST containing the fields version, api_key, data, where:

  • version is currently the number 3
  • api_key or identity_secret_key is the API key used to validate your events or the Identity secret key for your app. If you’re using the Swrve user ID, you must use the app API key for authentication. However, if you’re using an external user ID, you must send the Identity key.
  • data is an array of events of normal format, but with the addition in each one of either a “user” string field containing the Swrve user ID or an “external_user_id” string field containing an external user ID.

Error codes

See Session Start.

Code Text Description
400 Batch limit exceeded The batch size contains too many events or is too big. Try reducing the size of the batch and resending the request.

  • Maximum events per batch: 10,000
  • Maximum UTF-8 characters per batch: 4MB
429 Rate limit exceeded
429 Alias resolution is at capacity, try again later The app is trying to perform too many alias resolutions or something is wrong on the Swrve server side. Try resending the request later and reducing the rate of requests. No events from the batch will have been submitted.

Output parameters

Parameter Presence Description
nonexistent_external_user_ids Required A JSON array, containing any external_user_ids which could not be found, if external_user_ids were used in the request.

For example:

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