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.

See our Introduction to SiteSpect Engine API in our knowledge base.

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.