Last modified November 22, 2014 by Gordon Glauser

Swrve A/B Test API

The Swrve A/B Test API enables you to fetch resources held in the Swrve service according to the different variations that are available to each user in the app. The resources are returned in JSON format.
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?

Get Resources

This API call gets the full list of resources available (with full attribute data).

Request Method

GET

URL

US

https://<app_id>.content.swrve.com/api/1/resources

EU

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

Example

US

EU

URL Parameters

Parameter Presence Description
api_key Required The api_key for your app.

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
429 Rate Limit For This App Exceeded The app is sending too many requests per second. Try sending requests less frequently or use a sleep and retry statement.
401 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. Use cached data if possible.

Get User Resources

This API call retrieves the list of resources for a given user ID (with full attribute data) after applying the A/B test variations applicable to this user ID. This API call has the same effect as performing the following steps:

  1. Calling /resources/ to download a list of resources for the app.
  2. Calling /user_resources_diff/ to get a list of changes that are applicable to a particular user.
  3. Applying the changes to the items.

Request Method

GET

URL

US

https://<app_id>.content.swrve.com/api/1/user_resources

EU

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

Example

US

EU

URL Parameters

Parameter Presence Description
api_key Required The api_key for your app.
user Required The user ID for the current user.
app_version Required for version restricted A/B tests. This is a short string that identifies the version of the application that the user is currently using. This is used by Swrve to determine which A/B tests are applicable for this particular version of the app.
To restrict an A/B test to one or more versions of your app, your app must identify the app version each user is currently running before or when that user’s app session makes any call to the Swrve API. The attribute you must send with each API request is the app_version. If no app_version information is sent, the most recent value sent for that specific user is used. If no app_version attribute has ever been sent for that user (or for any users), no A/B tests are served and the app-restricted A/B test will have no participants.
joined Required for new user A/B tests. This value represents the time that the user first joined the app. Typically, this is the install date for the app or the date that the user first used it. Times must be represented as milliseconds since the epoch, UTC.
To enable deployment of A/B tests to users who are new since the time an A/B test was started, you must ensure that the app’s request for users’ A/B test resource differences is accompanied by the joined parameter. If you are not sending this parameter with the A/B test queries and you launch an A/B test that targets new users, the A/B Test API does not distribute the test to any users. If you are using the iOS SDK, however, this parameter is automatically handled.

Error Codes

See Get Resources.


Get User Resources Diff

This API call retrieves the difference in resources from the standard app resources, for a given user, after applying the A/B test variations applicable to this user ID.

Request Method

GET

URL

US

https://<app_id>.content.swrve.com/api/1/user_resources_diff

EU

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

Example

US

EU

Example Output

URL Parameters

Parameter Presence Description
api_key Required The api_key for your app.
user Required The user ID you want the resources to match.
app_version Required for version restricted A/B tests. This is a short string that identifies the version of the app that the user is currently using. This is used by Swrve to determine which A/B tests are applicable for this particular version of the app.
To restrict an A/B test to one or more versions of your app, your app must identify the app version each user is currently running before or when that user’s app session makes any call to the Swrve API. The attribute you must send with each API request is the app_version. If no app_version information is sent, the most recent value sent for that specific user is used. If no app_version attribute has ever been sent for that user (or for any users), no A/B tests are served and the app-restricted A/B test will have no participants.
joined Required for new user A/B tests. This value represents the time that the user first joined the app. Typically, this is the install date for the app or the date that the user first used it. Times must be represented as milliseconds since the epoch, UTC.
To enable deployment of A/B tests to users who are new since the time an A/B test was started, you must ensure that the app’s request for users’ A/B test resource differences is accompanied by the joined parameter. If you are not sending this parameter with the A/B test queries and you launch an A/B test that targets new users, the A/B Test API does not distribute the test to any users. If you are using the iOS SDK, however, this parameter is automatically handled.

Output Parameters

Parameter Description
uid The UID of the resource that varies.
item_class The item_class field of the resource that varies. This field has the value that the item_class has in the resource editor.
You can modify the item_class field as part of an A/B test. If you do, then this field is the original value from the item begin tested. The diff field (below) contains the new value of the item_class for the current user.
The item_class field is not required to be present in a resource. If it is not present, the value of this field is the empty string (“”).
diff The difference between the original and updated values of the resource for the user resulting from an A/B test. For example:[{“uid”:”com.unicode_string”,”item_class”:””,”diff”:{“text”:{“old”:”I ♡ mobile”,”new”:”I ❤ mobile”}}}]
old The value of the attribute being testing in the original resource.
new The value with which the attribute being tested should be replaced for the current user.

Error Codes

See Get Resources.


Get Tests

This API call retrieves a list of all the A/B tests that have been created in the system. This lists all tests with their attributes along with status attributes indicating whether the test has started or finished, how long the test has been running for, how many users have converted in each test and what the variants for each test are.

Never call this from within your app. This API call is intended for use by app administrators to query Swrve A/B tests, and is not designed for high levels of traffic.
The root of the URL for this API call is different to the other A/B test API calls.

Request Method

GET

URL

US

https://dashboard.swrve.com/api/1/abtests

EU

https://eu-dashboard.swrve.com/api/1/abtests

Example

US

EU

Example Output

URL Parameters

Parameter Presence Description
api_key Required The api_key for your app.
personal_key Required The personal_key for your app.

Output Parameters

Parameter Description
id The ID of the A/B test.
name The name that was given to the A/B test when it was created.
status The current status of the test (staged, started, aborted, finished and control chosen, finished and winning variant checked in, finished and winning variant not checked in).
url The relative URL of the A/B test.
items An array containing strings that represent the unique identifiers for the items that are being tested. This is the same item identier that is used in the purchase API, and the item API.
participants How many users have been included in the A/B test so far.
conversions The number of people who have completed the conversion event for the A/B test.
hours_running The number of hours elapsed since the test was started.
max_significance The statistical significance of the test so far.
winning_variant The variation index that has been chosen on finishing the test (blank if test is unfinished).
variants An array of objects containing attributes for the control and different treatments of the tested resources.

Error Codes

See Get Resources.