Example

Introduction to SiteSpect Engine API

The SiteSpect Engine API enables testing, optimization, and targeting for server-side, client-side, mobile apps, Over-the-Top (OTT) devices, kiosks, and any other application that makes HTTP calls. You can use the Engine API as a standalone system, but it is also complementary to SiteSpect proxy and client-side SDK approaches. You can use them all simultaneously and with consistency for the same end user.

High-Level Workflow for Engine API Testing

Before you get started with Engine API testing, take a moment to understand the basic workflow:

In SiteSpect:

In your native codebase (e.g., on your mobile app or server-side web app):

In use:

Getting Started

Enabling the Feature

Enable the feature in SiteSpect. See SiteSpect Engine API to learn how. When you enable the Engine API feature, SiteSpect creates a new Set called Engine API. The new Set exists only for organizational purposes, since you can add Engine API Campaigns to any non-overlay set, such as Experiments. In addition, you can enable normal web Campaigns to also work with the Engine API in the A/B Campaign Builder in the Advanced Settings area.

Note that the API endpoint follows this convention:

https://www.yourwebsite.com/__ssobj/api

Creating a Campaign in the SiteSpect UI

  1. Create an Engine API Campaign in the SiteSpect user interface, just as you would for any other type of Campaign. Using the A/B Campaign Builder, follow these steps:
    • Select New, A/B Campaign.
    • In the General section of the page, select Engine API from theType drop-down.
    • Define Variations.
    • Add Metrics and choose a KPI. In the Metrics section of the page, drag any Metrics you want to add to the Campaign from the Metrics List area to Assigned Metrics area. In addition, select a Metric and drag it to the Key Performance Indicator area. All Metrics have IDs that your application uses to send visitor behavior data to the SiteSpect engines.
    • Add Audiences. In the Audience section on the page, drag and drop any Audiences to set targeting rules for assignment.
  2. Save the Campaign. When you save the Campaign, SiteSpect automatically assigns a unique ID to each Variation Group. You will use these IDs to determine what your different users see.
  3. Change the Campaign Status to Live. Your API calls won’t work until the Campaign is live. Test it out on a limited set of users determined by an Audience.

Get User Assignments

Example Request


http://www.mysite.com/__ssobj/api

Example Response


{
	132186: {
		"Name": "Variation Group 1",
		"AsmtCounted": false,
		"Metrics": [
			{
				"Name": "Add to Cart",
				"ID": 113325,
			},
			{
				"Name": "Content: Home Page View",
				"ID": 113332,
			},
			{
				"Name": "Purchase",
				"ID": 113329,
			},
		],
		"Control": false,
	},
	"cookies": {
		"SSLB": "1",
		"SSRT": "UqCKXAAAAA",
		"SSSC": "808.G6668318472327500536.1|4876.132186",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},

Make an API call to retrieve user IDs, Variation Group IDs, and user cookies.

Store Variation Group IDs and user cookies. All subsequent API calls must include the SSID and SSRT cookies with the API calls.

Count the User In a Campaign

Example Request


Count a user in the Variation Group ID (VGID) 132186:
{
	"visits": [{
		"AsmtCounted": ["132186"],
	}],
	"cookies": {
		"SSRT": "UqCKXAAAAA",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},

Example Response


The "AsmtCounted" attribute confirms that the user was successfully counted in VGID 132186:
{
	132186: {
		"Name": "Variation Group 1",
		"AsmtCounted": true,
		"Metrics": [
			{
				"Name": "Add to Cart",
				"ID": 113325,
			},
			{
				"Name": "Content: Home Page View",
				"ID": 113332,
			},
			{
				"Name": "Purchase",
				"ID": 113329,
			},
		],
		"Control": false,
	},
	"cookies": {
		"SSLB": "1",
		"SSRT": "UqCKXAAAAA",
		"SSSC": "808.G6668318472327500536.1|4876.132186",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},
  1. Once a user has been exposed to a Variation, or would have been exposed if assigned to a Control Group, make an API call to mark the user as counted.
  2. Include SSID and SSRT cookie values with the call. You can pass those values as attributes in the JSON request body (also known as the payload) or as regular HTTP header cookies.

Collect User Data and Measure User Behavior

Example Request


Capture a hit for Metric IDs 113325 and 113329:
{
	"visits": [{
		"Data": {
			"113325": {
				"Hits": 1
			},
			"113329": {
				"Hits": 1
			},
		},
	}],
	"cookies": {
		"SSRT": "UqCKXAAAAA",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},

Example Response


{
	132186: {
		"Name": "Variation Group 1",
		"AsmtCounted": true,
		"Metrics": [
			{
				"Name": "Add to Cart",
				"ID": 113325,
			},
			{
				"Name": "Content: Home Page View",
				"ID": 113332,
			},
			{
				"Name": "Purchase",
				"ID": 113329,
			},
		],
		"Control": false,
	},
	"cookies": {
		"SSLB": "1",
		"SSRT": "UqCKXAAAAA",
		"SSSC": "808.G6668318472327500536.1|4876.132186",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},
  1. Make an API call to send a list of Metric IDs that the user has triggered. Previous examples show the list of Metrics and corresponding IDs for Campaigns that a user is assigned to.
  2. Include SSID and SSRT cookie values with the call. You can pass those values as attributes in the JSON request body (also known as the payload), or as regular HTTP header cookies.

Target a User with a Campaign

Example Request


Target existing customers, using a “CustomerID” cookie:
{
	"cookies": {
		"CustomerID": "123456",
	},
},

Example Response


{
	132186: {
		"Name": "Original",
		"AsmtCounted": false,
		"Metrics": [
			{
				"Name": "Add to Cart",
				"ID": 113325,
			},
			{
				"Name": "Content: Home Page View",
				"ID": 113332,
			},
			{
				"Name": "Purchase",
				"ID": 113329,
			},
		],
		"Control": false,
	},
	"cookies": {
		"SSLB": "1",
		"SSRT": "UqCKXAAAAA",
		"SSSC": "808.G6668318472327500536.1|4876.132186",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},
  1. For targeting and personalization purposes, the Engine API allows you to pass information or attributes about users in the assignment call. That information dictates which experience a user sees.
  2. In the UI, use regular Audiences to match on these additional attributes and target users for specific Campaigns. The example targets users with a CustomerId cookie. Make sure to include the Audience in your Campaign.

Test Without Resubmitting or Changing Your Mobile or Server-Side App

Example Request


{
	"cookies": {
		"SSRT": "UqCKXAAAAA",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},

Example Response


Notice the “VariationGroup_LiveVariables” that allows you to retrieve the content and apply it in your app code base:
{
	132186: {
		"Name": "Original",
		"AsmtCounted": false,
		"Metrics": [
			{
				"Name": "Add to Cart",
				"ID": 113325,
			},
			{
				"Name": "Content: Home Page View",
				"ID": 113332,
			},
			{
				"Name": "Purchase",
				"ID": 113329,
			},
		],
		"Control": false,
		"VariationGroup_LiveVariables": {
			"promotion-text": "Get 20% OFF today!"
		},
	},
	"cookies": {
		"SSLB": "1",
		"SSRT": "UqCKXAAAAA",
		"SSSC": "808.G6668318472327500536.1|4876.132186",
		"SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA"
	},
},
  1. For testing text, labels, colors, and other related use cases, use Live Variables.
  2. Live Variables allow you to define different values for your test Variations without having to resubmit the app to the store.
  3. The example defines alternate content for a promotion.
  4. The Live Variables are included in the response call to the EngineAPI for users assigned to this particular Variation Group.

Domain and Endpoint

You can access the API through a single endpoint based on your SiteSpect environment.

By default, the Engine API domain is based on your Site ID:
https://engine-[SiteID]p.sitespect.net

You can use your own domain for Engine API traffic:
https://api.example.com

If your domain is already routed through SiteSpect, you can make Engine API requests to your domain and path __ssobj/api:
https://www.example.com/__ssobj/api

All communication is over SSL and the main endpoint is just the root domain (base URL). Data passed in the body of POST calls is structured in JSON. The API does not require authentication.

API Calls

A GET call makes an Assignment and returns Campaign data, wrapped around Variation Group IDs in a hash that includes all Metrics and Live Variables that are part of the Campaign. A POST call sends visitor behavior data by populating those Metrics and setting counted state for the visit. Both POST and GET return fresh Assignment Data and thus, you can just use the POST method for API calls.

In a typical scenario, you want to make a GET request when the session starts and make the POST call whenever any Metrics are triggered. You can pass visitor behavior with Metrics at any time; in addition, you can pass multiple Visits and Metrics in one call. Each Metric must include hits data (how many times the behavior occurred) and optionally, Metrics can also include a Value Capture, for example, an average order amount.

These Metrics are stored within the context of a visit based on the User Session Timeout settings on the User Tracking page (typically set to 30 minutes). Each GET or POST call extends session timeout. In addition, the Maximum Visits Expiration and Previous Visit Time Expiration settings at the Campaign level affect how visits are processed.

For example: With default settings, an initial GET request starts the session and subsequent GET or POST requests will extend that session and track all Metrics for that visit. A GET or POST request that occurs 30 minutes later will be treated as a new second visit for the user and associated Metrics will be tracked in that new visits.

GET Assignments

Example Request


#Before you can make any visits, you have to be assigned.

curl https://engine-1p.sitespect.net/

Example Response


#Hash keys are Variation Group IDs so the response below shows that the current assignment is Variation Group 2 (in Campaign 1). It is not necessary to keep track of Campaigns, only the Variation Groups of Campaings.

{
    "88" : {
            "Name" : "Version B",
            "Control" : false,
            "AsmtCounted" : false,
            "Metrics" : [{
                "Name" : "Metric A",
                "ID" : 151
            }]
   }
}

#GET response with format=array :

{
	"Site_ID" : "123",
	"Campaigns" : [{
		"Name" : "New Checkout",
		"VariationGroup" : {
			"Control" : false,
			"Name" : "Variation Group 1",
			"AsmtCounted" : false,
			"Metrics" : [{
				  "Name" : "Metric A",
				  "ID" : 1323421
			  }]
			"ID" : "123212",
		},
		"ID" : "93123",
	}]
}


An API call that retrieves Campaign data and Assignments from SiteSpect. The response, structured in JSON, includes the Variation Groups that the visitor is assigned to.

SiteSpect uses cookies to track assignment, which you must send in subsequent calls. For convenience, you can pass/receive cookies and headers in the body of the request/response.

You can pass format=array as a query parameter to see the response formatted using an array structure, which is more convenient for Java/Android.

The important data points to store and track are: Variation Group ID, Metric ID, and AsmtCounted.

Resource URI

https://engine-[SiteID]p.sitespect.net

GET RESPONSE BODY

{
   "VariationGroupID": {
     "QuickChange": string,
     "LiveVariables": json,
     "Control": boolean,
     "VariationGroupName": string,
     "AsmtCounted": boolean,
     "Metrics": [{
         "MetricID": number,
         "MetricName": string
     }],
   },
   ...
}

POST Visits

An API call to send visit data to SiteSpect. Visits and counted state are passed in the body of the request, structured in JSON. Multiple Metrics and visits can be sent in one call. The response includes Assignment Data and updates SiteSpect cookies (same as GET response)

SiteSpect uses cookies to track assignment, so they need to be sent in this request. For convenience, you can pass/receive cookies and headers in the body of the request/response.

By default, SiteSpect counts visits according to the User Session Timeout setting in the Manage, Site Settings, User Tracking area, typically set to 30 minutes (1800 seconds). SiteSpect evaluates the last request time via SSRT cookie to determine if the visit should be extended by the User Session Timeout amount or if the request should be tracked as a new visit.

Example Request

curl -X POST -H 'Content-Type: application/json' -d 
{
    "visits" : [{
            "AsmtCounted" : ["88"],
            "Data" : {
                "151" : {
                    "Hits" : 1
                }
            }
    }]
}
https://engine-1p.sitespect.net/

Example Response


{
    "88" : {
            "Name" : "Version B",
            "Control" : false,
            "AsmtCounted" : false,
            "Metrics" : [{
                "Name" : "Metric A",
                "ID" : 151
            }]
   }
}

Resource URI

https://engine-[SiteID]p.sitespect.net

POST REQUEST BODY

{
  "visits": [{
    "AsmtCounted": ["VariationGroupID"],
    "time": Unix epoch,
    "newsession": boolean,
    "Data": {
      "MetricID": {
        "Hits": number,
        "ValueCapture": number
      }
    }
  }]
}

Body Properties

Field Type Description
AsmtCounted Array Variation Group IDs to properly count the visit in the Campaign.
Data Hash Metric IDs and their hit count (Hits) and/or Value Capture
time Unix epoch time Optional: overrides the current visit time which can be important when storing and passing multiple visits later on.
newsession boolean Optional: overrides the default logic that uses the User Session Timeout setting and starts a new visit.


Metrics and counted state can also be updated with URL parameters, by passing a URL query parameter with a value of the visitor's URL location. SiteSpect evaluates that against the URL triggers in Metrics and updates hit and value capture data as well as counted state for the visit if you have set Count User When Triggered to Yes in a Metric.

Note: For domains that are routing through SiteSpect, Metrics can be populated in the usual manner, meaning through regular HTTP requests, so in that scenario, you might not need any POST visit data call.

Resource URI

https://engine-[SiteID]p.sitespect.net/?url={url-path}&count={number}

URL Parameters

Property Description
url-path Visitor's URL location.
number Numerical value that you want to capture in a Metric.

Targeting

Example Request:


#The following is an example of geo and device targeting by passing headers in body of the POST request:
curl -X POST -H 'Content-Type: application/json' -d \
{\
    "headers" : {\
            "User-Agent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/53.0.2785.143 Safari/537.36",\
            "True-Client-Ip" : "74.94.137.129"\
    }\
}\
https://engine-1p.sitespect.net/

Example Response


Note: For IP to geo translation, SiteSpect looks at the following headers in order: True-Client-Ip, X-Forwarded-For, Client-Ip, Forwarded-For, CLIENTIP
{
    "88" : {
            "Name" : "Version B",
            "Control" : false,
            "AsmtCounted" : false,
            "Metrics" : [{
                "Name" : "Metric A",
                "ID" : 151
            }]
   }
}

Personalization and targeting work with the Engine API the same way they work for any other type of Campaign. You set them up the same way in SiteSpect; the client initiating the API call to SiteSpect can pass different URL parameters, headers, and cookies to limit which visitors are assigned to the Campaign. Other targeting options like seasonality, past visitor behavior, or custom data sets are also available.

Keep in mind that if the client is a web server (as opposed to a browser) the information passed in the API call (such as IP, user-agent, and so on) is not a group of parameters from the visitor but parameters from the web server. In this situation, it makes sense to pass visitor data in the HTTP request. You can do this in a traditional way, by passing custom headers/cookies in the request.

For convenience, you can also pass custom header/cookie overwrites in the body of the request (in JSON) and SiteSpect will use these. If any cookies or headers are passed in the body, the response also shows headers and cookies in the body.

The following is the JSON structure for passing HTTP Headers or Cookies inside the body:

{
"headers":{"header1":"header_value1","header2":"header_value2"},
"cookies":{"cookie1":"cookie_value1","cookie2":"cookie_value2"}
}

Assignments and Counted State

In SiteSpect, visitors are assigned to Campaigns in the initial GET call. A POST call sends visit data to SiteSpect and reports if the assignment is counted (via AsmtCounted array). Visits that are counted are sticky (persist in their assignment according to Campaign settings) while visits that are not counted can be reassigned to other Campaigns in the next API request.

A visitor is counted when that visitor is exposed to a change in a Campaign. That visitor may also be counted when the visitor is exposed to the location in your website or app where the change exists, even if the visitor doesn't see the change because he or she is in the Control Group. In other words, that visitor is at the point where the change exists for other Variation Groups, so the visitor should be counted.

SiteSpect data is based on counting; as such, it is important for you to track this data. Using the Engine API for optimization requires tracking when a visitor is counted (for control and non-control experiences) in order to have accurate report data. Make sure to pass that counted state to SiteSpect in the API POST call for each associated Variation Group.

Cookies and Caching Data

Example Request:


curl "https://engine-1p.sitespect.net/"
#SiteSpect Cookies in the response
SSID=CACZTB0OAAAABAAnc6xYAu8DHCdzrFgBAAAAAAABAAAAJ3OsWAAV3Q5mAAH9PgwAJ3OsWAEA
SSRT=J3OsWABAAA
SSOD=AGIxABBAIABK8AYAGwAAAIcCU1gmc6xYApMKAFQAAACHAlNYJnOsWBoAGACvCQgAAW3zjEgAn4AMkwIEa2OUGmX

We recommend that you cache the Assignment and Campaign data when making the GET request. The Campaign data is a hash of Variation Groups and Campaign Metrics that you must use in the POST call to send visitor behavior data back to SiteSpect. You must also store the SiteSpect cookies that identify a visitor since these cookies must be sent in the POST call so that the Metrics are recorded for the correct visitor.

Note: For convenience, you can send and receive cookies in the body of the request.

The cookies are:

Note: These cookies may have been renamed on the Site Settings page for your Site.

Live Variables

Example Request:


curl https://engine-1p.sitespect.net/

Example Response


{
    "88" : {
            "Name" : "Version A",
            "Control" : true,
            "AsmtCounted" : false,
            "Metrics" : [{
                "Name" : "Metric A",
                "ID" : 151
            }],
            "LiveVariables" : {
                "custom_key" : "custom_value"
            },
	  "VariationGroup_LiveVariables" : {
                "custom_key" : "custom_value"
            },
    }
}

Live Variables is a JSON data layer that are managed in a Campaign or Variation Group and passed to all visits assigned to the Campaign. This allows you to specify dynamic variables that can be used in your application and changed or managed in SiteSpect. You can even use it for a mapping of Variation Group IDs to custom defined tokens that you use in the app to apply changes.

You can manage Live Variables in the New Build Flow by selecting Live Variables from the three-dot menu in the upper right area of the page. There you can insert any valid JSON data that you want to associate with the campaign. Once saved, this data will show up in the response of the Engine API GET and POST call.

Errors

The following is an example of error code structure from an Engine API POST call with incorrect body parameters:

{
    "errors" : {
	    "asmtcounted" : "Not a valid array of integers."
    }
}

Errors are returned using standard HTTP error code syntax and any additional information is included in the body of the response, JSON-formatted. Here are some standard API errors:

Error Code Text Description
400 Bad Request The request was invalid and further information is included in the error message.

A POST call with invalid JSON will return a status code 400 and an error message. In other cases listed below, the POST call returns with Assignment Data (same as a GET) and status code 200:

CORS

Normally, browsers block client-side requests across different origins. To help you work around this restriction, SiteSpect supports Cross-Origin Resource Sharing (CORS), which adds specific headers to the SiteSpect server response that allow such cross-domain communication.

Simple Example

The goal is to test new copy in a promotional area of the home page and measure call-to-action clicks from it. The following describes how that works:

The Engine API GET call lives on the web server and is initiated on the page where the text is displayed to the visitor, so counted state is always true. At this point, the web server makes the GET call for Assignment and shows the new copy if the assigned Variation Group ID matches the non-Control Identifier. The web server also stores the Metric ID and Variation Group ID.

The web server makes a POST call to the SiteSpect engines when the visitor clicks the call-to-action button and lands on a new page. Since the POST calls happen as soon as the visitor lands on the page, the Hits value is always 1 and Variation Group ID is added to the “AsmtCounted” array to track counted state.

Detailed Example

The goal is to redesign a shipping form in a checkout page and measure how that affects conversion. This is a client side Engine API implementation and all SiteSpect cookies persist and are transferred in Ajax API calls by default.

An Engine API Campaign has already been created in SiteSpect and the Original or Control Variation Group ID is 10 while the non-Control Variation Group ID is 11. The conversion Metric has been added to the Campaign and its ID is 100.

GET Assignments

JavaScript code added to the page makes an Ajax GET request to SiteSpect for Assignment Data. The call assigns the visit to a specific Variation Group of a Campaign and the ID is shown in the response.

Apply Changes

The code responsible for delivering the shipping form in checkout checks for a Variation Group ID in the response of a GET request. If the response contains VG ID 10, the original design is delivered and 10 is added to the AsmtCounted array. If the response contains VG ID 11, the new shipping form design is drawn on the page and 11 is added to the AsmtCounted array.

Send Visit Data

On the order confirmation page, JavaScript code makes an Ajax POST call to SiteSpect and sends AsmtCounted array and Data for the conversion Metric 100 in JSON structure (with Hits set to 1 and ValueCapture set to the average order value for the given order). When SiteSpect receives this call, it updates the counted state of the assigned visit and adds the Metric data into reports.