Last modified November 22, 2014 by Gordon Glauser

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

All API calls to <app_id>.api.swrve.com (or <app_id>.eu-api.swrve.com for EU-configured apps) are authenticated using the API key provided for the app.

This article references Swrve’s URLs for all data and content stored in both our US and EU data centers. Click 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. It is the responsibility of the developer integrating Swrve into their app to ensure they are supplying a unique user identifier. Swrve relies upon this uniqueness property to monitor DAU counts, New User counts and funnel progression. Consider the following when supplying the user identifier:

  • 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.
  • An account ID specific to your application can be helpful for keeping track of multi-device users.
  • Apple GameCenter ID is another option for users on iOS, but the requirement to use GameCenter 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.

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 <app_id>.api.swrve.com (<app_id>.eu-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

An event payload (swrve_payload) can be added and sent with every REST call to <app_id>.api.swrve.com (<app_id>.eu-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 proceeding Session Start and Purchase Events sections.

UTF-8 Encoding

Swrve recommends 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

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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 may 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

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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.


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

EU

Example of a Purchase Event with Payload

US

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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

EU

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

US

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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:

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

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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 Overview screen and can be part of funnels and so forth. The name of the event is Swrve.user_properties_changed.

The Segments Overview screen provides an overview of your user base divided by 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

EU

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

US

EU

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

US

EU

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

US

EU

URL Parameters

Parameter Presence Description
api_key Required The API key used to validate your events.
user Required The Swrve user ID.
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. 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

EU

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.

For this reason, Swrve recommends that you send session_start and then send the current batch of events.