SiteSpect Engine API Reference

Engine API is a simple and powerful REST API that enables programmatic communication with SiteSpect as an endpoint

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.

Table of Contents

• Overview
• High level flow for Engine API interaction
• Getting Started: Control Panel
• Working with API calls
• Reference
• Flow - Campaign Assignment and Counting
• Example
• Discussion
  • Live Variables

Overview

Engine API logic works in the same way as the proxy does. The user is assigned to a campaign when a request is made to the Engine API endpoint. That user can be counted in a campaign with a subsequent request.

Proxied Web vs. Engine API App

High level flow for Engine API interaction

An example:

1. The end user launches a mobile app on a smartphone. We’re using the smartphone as the example, but this could just as easily be pretty much any application that uses HTTP calls.
2. Your app makes an Engine API call to determine which Campaigns are assigned to the user, which correlate to the experience(s) the user should see. During the Assignment, the split for A/B Campaigns will occur placing the user into a Control or Variation Group.
3. Based on the response of the Engine API which includes one or more Variation Group IDs, the mobile app displays the experience(s) in the users visit.
4. Your app sends back a POST to Engine API reporting that the user is counted in the Campaign.
5. As the user progresses through their visit, your app makes API calls to capture user behavior and conversions, sending metric hits along the way (batching in a single call is an option as well).
6. SiteSpect will automatically close out the user's visit based on 30 minutes of inactivity.

Getting Started: Control Panel

Prerequisite: If Engine API is enabled for your configuration, you should see a Campaign Set called Engine API and be able to specify the Type: Engine API when creating a new Campaign. If you don't see this option, please work with your Account Manager to request this feature. 

Note: There is an option to enable Engine API from with Advanced Settings. The intent of this option is to be able to use a Campaign for both proxied traffic AND Engine API. This is a less common use case. If you want to use a Campaign dedicated to Engine API traffic, please use the above process to create a campaign that is of the Type: Engine API.

Create a Campaign

Create an Engine API Campaign from the SiteSpect Control Panel, just as you would for any other type of Campaign. Using the A/B Campaign Builder, follow these steps:

1. Select New, A/B Campaign.
2. In the General section of the page, select Engine API from the Type drop-down.
3. Create Variation Groups. You can also optionally create Live Variables.
4. 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 are used by your application to send visitor behavior data to the SiteSpect engines.
5. Add Audiences. In the Audience section on the page, optionally drag and drop any Audiences to set targeting rules for assignment.
6. Save the Campaign. When you save the Campaign, SiteSpect automatically assigns a unique ID to each Variation Group.
7. Retrieve IDs From SiteSpect for Variations, Metrics, and Audiences. You’ll use these in your API code.
8. Change the Campaign Status to Active-running. Your API calls won’t work until the Campaign is Active. Optionally test it out on a limited set of users by using a restricted Audience such as a header value.

Working with Engine API calls

It is recommended that when new to Engine API you test it by using your favorite environment. We use curl or Postman.

Resource URI

The API endpoint resource typically follows the convention of the first two but can be customized:

https://yourwebsite.com/__ssobj/api

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

https://api.yourdomain.com

The optional parameter ?format=array can be used to format the JSON response as an array.

Please work with our Solutions Architecture team for configuration changes.

Rules related to bot filtering

Making a request to the Engine API can be impacted by your site configuration. There are two types of User Agent bot rules that can affect your request.

• Pass-through: by default, there is a rule for the purpose of robot exclusion that specifies a User Agent must have at least 30 characters & one forward slash. Pass-through rules will not be active against Engine API traffic when the Configuration > Site Settings > Features setting "Enable Passthrough Rules for Engine API" is unchecked.
  
• IAB Robot Detection: If this feature is enabled, there is a rule "Exclude users not on the IAB/ABC International list of valid browsers" that will consider your request a bot if you don't send a valid User Agent. This setting is located in Configuration > Site Settings > User Tracking.

Both of these options are within the Configuration section of the SiteSpect Control Panel and require a special permissions to change. Please work with a SiteSpect resource if needed.

Using a valid browser User Agent will ensure your request is not considered a bot regardless of either of these settings.

User Tracking

When a user has not yet had any interaction with SiteSpect, they have no cookies. Cookies are used to track Campaign Assignment and counted status. Cookies must be used in subsequent visits so the user is properly tracked. A request with no cookies is considered a new user.

Cookies can be managed automatically (like in a browser) by using a cookie jar in your code environment. Optionally cookies can be managed in another way and passed  into the JSON payload in the body of the POST. When there are Engine API cookies in the JSON payload, any cookies that are passed as cookies would be ignored - the JSON payload take precedence.

The most recent cookie values should always be used. That is, the cookie set that was returned from the most recent request should be used in the next request.

Reference

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

JSON Request Body

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

    "url": "string",
    "cookies":
    {
        "SSRT": "string",
        "SSID": "string",
        "mycustomcookie": "string"
    }
}

Body Properties

None of the Body Properties are required for subsequent POSTs after the user has been counted in the visit. The act of counting makes that user "stick" and be included in the data set. More on counting in the next section.

Request headers can be used at will. These will be evaluated against Audiences and Metric Triggers.

Flow - Campaign Assignment and Counting

1. Get Assigned to Campaign(s)

Send a POST with an empty body at the beginning each new visit.

Examine the response to see which Campaign Variation Groups the user is assigned to.

Users (with cookies) who were assigned and counted in a previous visit will automatically stay assigned and counted in future visits.
Note: Because of how counting is sticky across visits, it is very important to have Metrics that align with the user experience and actions to provide proper insight into reporting.

Campaigns where the user was never counted in a previous visit will be reevaluated for assignment on each new call to the Engine API.

Also note, as you might expect, Campaigns that have been paused,  ended, or the user is expired from the visit, will no longer be represented in the response. Every time a POST is performed, the current list of Campaign Variation Group IDs will be returned along with their counted status.

2. Count User in Campaign(s)

Send a POST with "AsmtCounted": ["VariationGroupID"] with an array of Variation Group IDs (VGID) that you want the user counted in (and where they are not yet). VGIDs where the user is already reported as counted don't need to be included but doing so causes no harm.

Send a POST with for each Variation Group ID that the user should be part of. Optionally also send any Metric Hits at this time, and/or send them later in the visit.

"AsmtCounted": ["VariationGroupID"]

When a user is counted in a campaign, it is one way - meaning the user cannot be uncounted unless they expire from the campaign or the campaign status is changed to paused/ended.

Subsequent POSTs within a visit will make no change to the counted status. These additional POSTs serve to allow for sending metric hits or extend the active visit (expires after 30 minutes of inactivity).

Example

POST https://thewebsite.com/__ssobj/api

Response JSON

{
    "cookies":
    {
        "SSSC": "808.G7054646803462961394.1|4876.132187",
        "SSID": "CQBLsR0OAAAAAADkI-dh8jhBAOQj52EBAAAAAAAAAAAA5CPnYQIV3QwTAAFbBAIA5CPnYQEA",
        "SSRT": "5CPnYQADAA"
    },
    "132187":
    {
        "Metrics": [
        {
            "ID": 113325,
            "Name": "Add to Cart"
        },
        {
            "ID": 113329,
            "Name": "Buy"
        },
        {
            "ID": 108119,
            "Name": "Checkout: Order Value"
        },
        {
            "ID": 113332,
            "Name": "Content: Home Page View"
        }],
        "AsmtCounted": false,
        "Name": "Promotion 50%",
        "Control": false,
        "VariationGroup_LiveVariables":
        {
            "promotion-text": "Get 50% OFF today!",
            "promotion-banner": "https://www.site.com/img/banner-50.jpg"
        }
    }
}

In this example, the user has not been counted for the Variation Group 132187. The following JSON payload will count the user.

POST JSON request payload for the user to be counted and two metrics to be hit. The Data section with Metric hits is not required, AsmtCounted is the minimum requirement for counting the user.

{
    "visits": [
    {
        "AsmtCounted": ["132187"],
        "Data":
        {
            "113325":
            {
                "Hits": 1
            },
            "113329":
            {
                "Hits": 1
            }
        }
    }]
}

Response JSON

{
    "132187":
    {
        "Name": "Promotion 50%",
        "Control": false,
        "VariationGroup_LiveVariables":
        {
            "promotion-banner": "https://www.site.com/img/banner-50.jpg",
            "promotion-text": "Get 50% OFF today!"
        },
        "Metrics": [
        {
            "Name": "Add to Cart",
            "ID": 113325
        },
        {
            "Name": "Buy",
            "ID": 113329
        },
        {
            "Name": "Checkout: Order Value",
            "ID": 108119
        },
        {
            "Name": "Content: Home Page View",
            "ID": 113332
        }],
        "AsmtCounted": true
    },
    "cookies":
    {
        "SSRT": "gSTnYQADAA",
        "SSID": "CQBACR0OAAAAAADkI-dh8jhBAOQj52EBAAAAAAAAAAAA5CPnYQIV3QwTAANbBAIA5CPnYQEA",
        "SSOD": "AGiCAAAAJACtugEAAQAAAIEk52GBJOdhAQCxugEAAQAAAIEk52GBJOdhAQAAAA",
        "SSSC": "808.G7054646803462961394.1|4876.132187"
    }
}

The "AsmtCounted" is now showing as true for this Campaign VGID.

Discussion

Variation Group IDs are unique and tied to a campaign. A user will get assigned to only one Variation Group ID (VGID) per campaign as they normally do. Each VGID will return the following data every time a POST is made:

• Name
• Control: boolean (is the Variation Group a control or not)
• AsmtCounted: boolean (has the user been counted in this Campaign Variation Group yet
• All available metrics that are associated with that Campaign
• The SiteSpect Cookie Set (returned in JSON even when tracking in a cookie jar)
• Live Variables if used

What are Live Variables

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.

Live Variables can be used at the Campaign level and Variation Group level. They are manged in the New Build Flow either by selecting Live Variables from the three-dot menu in the upper right area of the page, or from each Variation Group. 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 POST.

Cookies

• SSID: Visitor Tracking - A persistent cookie that tracks a visitor over time. (Required)
• SSRT: Recent Request Time - Stores the data and time of the visitor's last request to determine if the visit has timed out. (Required)
• SSOD: Additional Data Storage - Stores additional Campaign data for the visitor, including the hit rating value and the baseline Metric hit data.

Note: cookie naming can be something other than what is stated here based on your individual configuration.

CORS

If using Engine API from the browser, SiteSpect supports Cross-Origin Resource Sharing (CORS), which adds specific headers to the SiteSpect server response that allow such cross-domain communication.

Visit length

Additional POSTs within a visit will allow SiteSpect to calculate visit time. If you see a visit
length of 0 in your data export, that indicates a single POST for that visit. The visit time will
represent the time between the first and last POST in a visit. A visit is automatically closed out
after 30 minutes of inactivity so additional Engine API communication can be used to extend a
visit. Conversely there is newsession boolean that can used to force a user into a new session.

Previewing /QAing

There are a couple of options to test showing your changes.

1. Determine your own custom flag that will instruct your code to apply the changes that would be applied from the signal from the Engine API response. For example using a custom header a custom URL parameter.
2. Temporarily add an Audience to your campaign that restricts assignment. This could be a header, URL parameter, or IP address. Once the Audience is added, the campaign can be set to active with no risk of assignment from your normal traffic. If, for example, you have a Control and two Variation Groups - you would need to clear cookies and get assigned as a new user until you were randomly assigned to each Variation Group* (see note below). Once you have completed that validation, the custom Audience can be removed.

POST /__ssobj/api?AppVG=2235223

AppVG is your chosen parameter name, and 2235223 is the system provided Variation Group ID.

POST body

{
    "visits" : [{ 
        "AsmtCounted" : ["2235223"]
    }]
}