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/1/resources*

EU

*https://<app_id>.eu-content.swrve.com/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:

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/1/user_resources*

EU

*https://<app_id>.eu-content.swrve.com/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/1/user_resources_diff*

EU

*https://<app_id>.eu-content.swrve.com/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:
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://<app_id>.content.swrve.com/1/abtests*

EU

*https://<app_id>.eu-content.swrve.com/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.