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
curl -G -d "api_key=<api key>" https://<app_id>.content.swrve.com/api/1/resources
EU
curl -G -d "api_key=<api key>" https://<app_id>.eu-content.swrve.com/api/1/resources
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:
- Calling /resources/ to download a list of resources for the app.
- Calling /user_resources_diff/ to get a list of changes that are applicable to a particular user.
- 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
curl -G -d "api_key=<api key>" -d "user=" -d "joined=1327068001000" -d "app_version=1.8a" https://<app_id>.content.swrve.com/api/1/user_resources
EU
curl -G -d "api_key=<api key>" -d "user=" -d "joined=1327068001000" -d "app_version=1.8a" https://<app_id>.eu-content.swrve.com/api/1/user_resources
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
curl -G -d "api_key=<api key>" -d "user=" -d "joined=1327068001000" -d "app_version=1.8a" https://<app_id>.content.swrve.com/api/1/user_resources_diff
EU
curl -G -d "api_key=<api key>" -d "user=" -d "joined=1327068001000" -d "app_version=1.8a" https://<app_id>.eu-content.swrve.com/api/1/user_resources_diff
Example output
[
{
"uid":"band",
"item_class":"building",
"diff":{
"description":{
"old":"A bandstand",
"new":"A band"
}
}
}
]
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.
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
curl -G -d "api_key=<api key>" -d "personal_key=<personal_key>" https://dashboard.swrve.com/api/1/abtests
EU
curl -G -d "api_key=<api key>" -d "personal_key=<personal_key>" https://eu-dashboard.swrve.com/api/1/abtests
Example output
[
{
"id":1,
"name":"Band A/B Test",
"description":"A/B testing the Band item",
"status":"started",
"url":"/apps/1/ab_tests/1",
"items": ["band"],
"participants":122,
"conversions":5,
"hours_running":12,
"max_significance":0.0,
"winning_variant":"",
"variants":[
{
"index":0,
"uid":"band",
"pop_size":0.5,
"name": "Control",
"variance":{}
},
{
"index":1,
"uid":"band",
"pop_size":0.5,
"name": "Treatment 1",
"variance":
{
"animated": "false",
"width": "124"
}
}
]
}
]
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.