Introduction to SiteSpect Engine API

Use the Engine API for mobile app, service side, or client side testing 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. 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.

An example:

  • 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/visit, the app makes API calls to capture user behavior and conversions. This allows SiteSpect to measure the effectiveness of tests in the mobile app.

Getting Started

Enable the Engine API.

This is a step that the SiteSpect Solutions Architecture team will perform. Please work with your Account Manager to request this feature if not already enabled.

When the Engine API feature is enabled, SiteSpect creates a new Set called Engine API. You will also see the Type and Set select list fields have the option for Engine API inside the Campaign Builder.

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.

Create a Campaign

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

Add API calls to your code

        Add API calls to your code (e.g., on your mobile app or server-side web app). For native apps, upload the new version to the appropriate app store.

        Note that the API endpoint typically follows this convention (but can be customized):
        https://www.yourwebsite.com/__ssobj/api

          API Call Traffic Flow

          From a logic perspective, Engine API works in the same way that proxied web traffic does in SiteSpect. When an Engine API Campaign is Active, you can make API calls to the Engine API domain and endpoint.

          There are two primary steps:

          1. Get Assigned: A GET call makes an Assignment and returns Campaign data, showing which Variation Group the user is assigned to and all Metrics that are part of the Campaign. The purpose is to see which campaigns are running,  the user is eligible for, and get assigned to a Variation Group.
          2. Get Counted: A POST call sends visit behavior data such as a Counted status and optionally Metric hits. A POST has a response BODY similar to a GET, and returns the state of Campaigns. The purpose is to Count the user in the Campaign when the user performs the actions or navigates to the page where they see the experience. It is only required to Count the user once per visit but additional Metric hits can be sent any time in the visit as they are triggered.

          It is very important to do a GET at the beginning of each visit before doing a POST to ensure:

          • The user is still eligible for assignment to the same campaign(s). e.g. The campaign status could have changed (to paused or ended) or the visit expiration settings could have been reached.
          • Assignment to newly launched campaigns happens as expected.
          • The user is entered into a new visit for existing running campaigns.

            In a typical scenario, you want to make a GET request when the visit 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 Metrics in one call. Each Metric must include hits data (how many times the behavior occurred) and optionally, Metrics can include a Value Capture, for example, an average order amount. Once the user is counted in the visit, a POST with Metric counts does not require the Variation Group ID as it does with the POST for Counted status.

            These Metrics are stored within the context of a visit based on the setting for User Session/Visit Timeout on the User Tracking page (ManageConfigurationSite SettingsUser Tracking). Each GET or POST call extends session/visit timeout. In addition, the Maximum Visits Expiration and Previous Visit Time Expiration settings at the Campaign level affect how visits are processed. You can find both in the Adanced Settings tab of the Campaign.

            Note: Client-side request to Engine API endpoints include CORS (Cross-Origin Resource Sharing) headers by default.

            There are examples of the GET and POST request and responses below and also on the Engine API Developers Portal (also linked at the bottom of this page).

              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.

              GET REQUEST

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

              RESPONSE

              { "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. The API does not require authentication.

              If your domain is already routed through SiteSpect (proxy implementation), then you can make Engine API requests to your domain and path:

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

              Or in the configuration there is an option for the Engine API domain that is based on your Site ID:

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

              Or you can use your own domain for Engine API traffic where the main endpoint is the root domain:

              https://api.yourdomain.com

              Please work with our Solutions Architecture team for configuration changes.

              Engine API Developer's Portal

              The Engine API Developer's Portal is a reference and contains some additional examples.