Skip to main content

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.

note

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.
tip

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.

CodeTextDescription
403No such external IDThe external user ID does not exist.
403Invalid Secret KeyCheck that your Identity secret key is correct.
429Alias resolution is at capacity, try again laterThe 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.

info

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​

*https://<app_id>.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​

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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_versionOptionalThe version of the application that the user is currently using.
swrve_payloadOptionalA 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.

CodeTextDescription
400Invalid ParameterThe request included an invalid parameter or an invalid JSON object, based on the specification.
403Invalid API KeyCheck that your API key is correct.
410API key no longer validThe 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.
503Service UnavailableAn 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​

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

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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_versionOptionalThe 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​

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

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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.
nameRequiredThe 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_versionOptionalThe 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​

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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.
nameRequiredTo update the contents of a user list, this value must be Swrve.user_tag_update.
swrve_payloadRequiredA 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​

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

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

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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.
itemRequiredThe ID of the item that has been purchased.
costRequiredThe integer amount of in-app currency spent on one item (see quantity).
quantityOptional (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.
currencyRequiredThe 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_versionOptionalThe version of the application that the user is currently using.
swrve_payloadOptionalA 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​

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

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

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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_idRequired for Google and unknown_storeThe 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.
costRequiredThe amount of real money that the user has spent. This value can be an integer or a floating point value.
quantityRequired for unknown_storeThe 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_currencyRequiredThis 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.
rewardsOptionalJSON 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_storeRequiredThe possible values are apple, google or unknown_store.
receiptRequired for Apple and GoogleA 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_signatureRequired for GoogleThe verifiable digital signature as a string.
app_versionOptionalThe version of the application that the user is currently using.
transaction_idRequired for Apple iOS7 receiptsiOS7 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.
note

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​

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

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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_currencyRequiredThe 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_amountRequiredThe 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_versionOptionalThe 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​

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

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

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

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

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

URL parameters​

ParameterPresenceDescription
user

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

identity_secret_key		RequiredThe 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_initiatedOptionalIf 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_nameOptional/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_versionOptionalThe version of the application that the user is currently using.
DateTimeOptionalThe 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 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​

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

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

URL parameters​

ParameterPresenceDescription
N/ARequiredA 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.

tip

Important notes:

Request method​

POST

URL​

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

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

URL parameters​

ParameterPresenceDescription
N/ARequiredA 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.

CodeTextDescription
400Batch limit exceededThe 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
429Rate limit exceeded
429Alias resolution is at capacity, try again laterThe 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​

ParameterPresenceDescription
nonexistent_external_user_idsRequiredA 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" ] }