Use the API to get a randomised variation for a project

API key

You need an API key to be able to use the API. Calling the API without a correct key will get you a 401 (Unauthorized) response.

For now, you need to reach out to support@symplify.com to receive an API key. Once you have your API key you can start using this feature.

 

Create the project

To be able to use the API for randomising a variation for a specific project you first need to create the project. To do this create a Server-side test project by following the instructions in the section The setup in Symplify in the Server-side documentation.

Note that creating a client side project will not work as the Symplify script will then allocate the project as soon as the project is active and will thus not wait for any API request.

 

Test the API request

To test the API request you can do a simple curl request and see that you get a randomised variation and a visitor ID back in response.

curl --location 'https://api.prod.condev.symplify.com/v1/projects/123456789/variation?status=ignored' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...'

Note that you need to change to the correct projectId in the URL above and also change to the API key for the website that the project is set up for. Also add the ?status=ignored parameters to be able to call this even though the project isn't active.

 

Procedure

For best performance we recommend only calling the API if the project/variation is not already in the cookie (i.e if the visitor has not been allocated the project yet).

When calling the API you will get a response back with the given variationId (and a visitorId). You will need to set the projectId and variationId in the cookie called sg_cookies for the project to be allocated for the visitor. As soon as this information is added to sg_cookies, the Symplify script will allocate the project and start tracking the visitor.

This cookie ( sg_cookies ) is a persistant cookie and as long as the visitor got the cookie you do not need to call the API again. Instead you should fetch the given variationId for the project and serve the code changes for that given variation.

Below are the proposed steps for this procedure;

  • Check if the cookie sg_cookies exist
    • If not, call the API with the projectId and then create the cookie and set the project and variation in the cookie
    • If sg_cookies exist, check if the project exist in the cookie
      • if the project does not exist in the cookie, call the API with the visitorId (visid) in the cookie to get a randomised variation and then serve the code for that variation and set the project and variation in sg_cookies
      • If the project exist, fetch the variationId for the project from sg_cookies and serve the code for that variation.

 

 

Calling the API with visitorID

Calling the API with visitorId as a parameter will get you the same randomised variation every time for that project. If the cookie (sg_cookies) already exist and has a visitorId (visid), we recommend you to call the API with that visitorId.

If the cookie does not exist or does not yet has a visid, you can call the API without the visitorId parameter.

curl --location 'https://api.prod.condev.symplify.com/v1/projects/123456789/variation?visitorId=da370d46-4908-426b-916d-9b3ceb6597bd' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...'

Note that the project needs to be active for this request to give back a randomised variation. If you are just testing this, please use the ?status=ignored parameters (see Test the API request above)

 

{
  "error": "INVALID_STATUS",
  "message": "Project 123456789 not active"
}

If the project is not active you will get this error message back. We recommend you to set this up as if an error is received then serve the default version of the page/your code.

 

Managing the cookie

You will need the websiteId to be able to set/get the cookie ( sg_cookies ). To get this ID go to My websites and then copy the ID for the correct website (see image below).

 

Creating the cookie

Create a cookie called sg_cookies. Make sure it is set on the highest possible domain (i.e if your website URL is https://www.examplesite.com set the cookie domain to .examplesite.com ). Then set the following information. The value of the cookie needs to be an Object and have the structure displayed below.

{"{websiteId}":{ // string
  "{projectId}":[{variationId}], // string : Array<number>
  "{projectId}_ch":1, // string : number
  "visid":"{visitorId}", // string : string
},"_g":1} // string : number

Note that the projectId will need to be set twice, the one ending in _ch with a value of 1, tells the Symplify script that this project has been allocated and that it should start tracking the visitor for this project.

 

Example with real values;

{"5619945":{
  "192525360":[11320509],
  "192525360_ch":1,
  "visid":"da370d46-4908-426b-916d-9b3ceb6597bd",
},"_g":1}

 

Set the project and variation in an existing cookie ( sg_cookies )

If sg_cookies already exist you only need to set the project and variation information. This is done by adding a key value pair where the projectId is the key and the variationId is the value set in an array. You also need to add the projectId + '_ch' as a key and the value 1 to allocate the project for the visitor. See examples above for this.

Note that this only needs to be set once, and then the Symplify script will handle the allocation and tracking for this project.

 

Fully populated sg_cookie example

Below is how a fully populated sg_cookies will look like after the Symplify script added the tracking data.

{"5619945":{
  "192525360":[11320509],
  "rf":"",
  "lv":1708674113751,
  "pv":1,
  "tv":1,
  "192525360_ch":1,
  "aud_p":[192525360],
  "visid":"da370d46-4908-426b-916d-9b3ceb6597bd",
  "commid":"e9f1d6f0-1e66-41a3-99f4-1abf8ac33533"
},"_g":1}

 

Fetch the variation IDs

When the project setup is done you will need to get the variationId:s for your project as you will need to use them in your if-statement/switch in your code. You can do a curl request to fetch these. You should receive a list of all variations for the project. From this list you can get the variationIds that you need to use in your if-statement/switch. See example code for that further down in this documentation.

curl --location 'https://api.prod.condev.symplify.com/v1/projects/123456789/variations' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXV...'

Note that you need to change to the correct projectId in the URL above and also change to the API key for the website that the project is set up for. This can be called no matter project status.

 

Setting up the if-statement/switch in your code

Lets say we have have the following variationIDs in our project;
Original: 11320509
Variation 1: 11320510

Set up a if-statement/switch in your code that will serve the visitor the design/functionality based on variation received (see code example below).

When setting up the if-statement/switch for you variations we recommend always having a default case where you serve the default design and do not allocate the visitor with the project/variation (do not set the project in the cookie). This will handle if no variation matches (i.e if the project is not active yet or you get some other error response from the API). See example below;

switch(variation) {
    case 11320509: {
        // Serve the Original
        // Set the project and variation in cookie 
        break;
    }
    case 11320510: {
        // Variation 1 design is served
        // Set the project and variation in cookie
        break;
    }
    default: {
        // project not active, serve the default design of your page
        // Set the project as null allocated in cookie by only setting {projectId}_ch":-1
        // (and thus not "{projectId}":[{variationId}] in the cookie)

Note that you should have the Original variation here as well and serve the default design/functionality if that is received. A visitor who get the variationId for the Original will be part of the project and thereby tracked.

 

Activating the project

When everything is tested and setup in your code you need to activate the project in the Symplify UI to start tracking visitors for this project. Remember to remove the ?status=ignored parameters from your request URL before you activate, otherwise the project will keep giving you randomised variations even after the project is paused in the Symplify UI.

 

Deactivating the project

When you want to stop the project you need yo go to the Symplify UI and click the project and select Pause. This will build a new version of the script where the project is not included. The visitors will get the new version of the script and as the project is not present the script will automatically remove the project and variation information from the cookie (sg_cookies).

Now you can remove the if-statement/switch for this project in you code.

Was this article helpful?
0 out of 0 found this helpful