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. While you can use the Engine API as a standalone tool, it is meant to be complementary to the SiteSpect proxy and client-side SDK approaches. You can use them simultaneously and consistently for the same end user.

This topic introduces the Engine API and covers the following:

More information is available on our Developer's Portal.

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):

  • Add API calls to your code. For native apps, upload the new version to the appropriate app store.

In use:

  • 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 a server-side web application, OTT device, a kiosk, or pretty much any application that uses HTTP calls.
  • While loading, your app makes an Engine API call to SiteSpect to determine which experience the user should see in the mobile app (i.e., what Variations the user should see).
  • Based on the result of this Engine API call, the mobile app displays the correct combination of Variations.
  • As the end user progresses through a mobile app session, the app makes API calls to capture user behavior and conversions. This allows SiteSpect to measure the effectiveness of tests in the mobile app.

Traffic Flow

The following shows the flow in action:

Getting Started

Enabling the API

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

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:

  1. Select NewA/B Campaign.
  2. In the General section of the page, select Engine API from the Type drop-down.
  1. Define Variations.
  2. 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.
  3. Add Audiences. In the Audience section on the page, drag and drop any Audiences to set targeting rules for assignment.
  4. 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.
  1. 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.

Adding API Calls to Your App

Now that you’ve turned on the feature and created an Engine API Campaign in SiteSpect, you need to modify your app code to use the API.

Get User Assignments

  1. Make an API call to retrieve user IDs, Variation Group IDs, and user cookies,
  2. Store Variation Group IDs and user cookies. All subsequent API calls must include the SSID and SSRT cookies with the API calls.

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

Count the User in a Campaign

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”.

Include SSID and SSRT cookie values with the call. You can pass those values as attributes in the JSON request body (also known as payload), or as regular HTTP header cookies.

POST Example

Count a user in the Variation Group ID (VGID) 132186:

{ "visits" : [{ "AsmtCounted" : ["132186"] }], "cookies": { "SSRT": "UqCKXAAAAA", "SSID": "CABGJB0OAAAAAABSoIpc-JJBAFKgilwBAAAAAAAAAAAAUqCKXAAV3QwTAAFaBAIAUqCKXAAA" } }

RESPONSE

The "AsmtCounted" attribute confirms that the user was successfully counted in VGID 132186:

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

Collect User Data and Measure User Behavior

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.

Include SSID and SSRT cookie values with the call.You can pass those values as attributes in the JSON request body (also known as payload), or as regular HTTP header cookies.

POST Example

Capture a hit for Metric IDs 113325 and 113329:

{ "visits" : [{ "Data" : { "113325" : { "Hits" : 1 }, "113329" : { "Hits" : 1 } } }], "cookies": { "SSID": "CAD4Hx0OAAAAAAAexItcEL1BAB7Ei1wBAAAAAAAAAAAAHsSLXAAV3QwTAAFZBAIAHsSLXAAA", "SSRT": "HsSLXAAAAA" } }

RESPONSE

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

Target a User with a Campaign

For targeting and personalization purposes, the Engine API allows you to pass information or attributes about users in the assignment call, which gets used to dictate which experience a user should be in.

In the UI, use regular Audiences to match on these additional attributes, and Target users into specific Campaigns. Here is an example for Targeting customers with a CustomerID cookie:

Make sure to include the Audience in your Campaign:

GET example

Target existing customers, using a “CustomerID” cookie:

{ "cookies": { "CustomerID": "123456" } }

RESPONSE

{ "132185": { "AsmtCounted": false, "Metrics": [ { "ID": 113325, "Name": "Add to Cart" }, { "ID": 113332, "Name": "Content: Home Page View" }, { "ID": 113329, "Name": "Purchase" } ], "Name": "Original", "Control": true }, "cookies": { "SSRT": "6QiMXAAAAA", "SSLB": "1", "SSID": "CABdph0OAAAAAADpCIxcnelBAOkIjFwBAAAAAAAAAAAA6QiMXAAV3QwTAAFZBAIA6QiMXAAA", "SSSC": "808.G6668714945053583773.1|4876.132185" } }

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

For testing text, labels, colors and other related use cases, use Live Variables.

Live Variables allow you to define different values for your test Variations, without having to resubmit the app to the store.

Here is an example for defining alternate content for a promotion:

The Live Variables are included in the response call to the EngineAPI for users assigned to this particular Variation Group.

POST example

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

RESPONSE

Notice the “VariationGroup_LiveVariables” that allows you to retrieve

the content and apply it in your app code base:

{ "132186": { "Metrics": [ { "Name": "Add to Cart", "ID": 113325 }, { "ID": 113332, "Name": "Content: Home Page View" }, { "ID": 113329, "Name": "Purchase" } ], "Name": "Variation Group 1", "Control": false, "VariationGroup_LiveVariables": { "promotion-text": "Get 20% OFF today!" }, "AsmtCounted": false }, "cookies": { "SSRT": "gwqMXAAAAA", "SSLB": "1", "SSSC": "808.G6668716705990051840.1|4876.132186", "SSID": "CACJJx0OAAAAAACDCoxcAAhAAIMKjFwBAAAAAAAAAAAAgwqMXAAV3QwTAAFaBAIAgwqMXAAA" } }

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 (proxy implementation), then 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.

Developer's Portal

To learn more about the Engine API, visit our Developer's Portal.