Engine API 2.0 (beta) Reference

The Engine API 2.0 provides a flexible way to integrate SiteSpect's experimentation platform into environments beyond the web, such as mobile apps, kiosks, and other applications.

The Engine API 2.0 requires a domain to be configured and routed through SiteSpect. Alternatively, a subdomain can be configured as a standalone endpoint (e.g. sitespect.yoursite.com).

To learn more about creating campaigns and metrics for Engine API 2.0, see How to Create Campaigns Campaigns and Metrics for Engine API 2.0.

Engine API 2.0 Endpoint

To retrieve assignments, variations, feature flags or capture metrics using the Engine API 2.0, make a POST request to the following endpoint:

POST /__ssobj/static/endpoint.json

The response will include data about the campaigns the user is assigned to, the variations within those campaigns, feature flags, metrics, and user information. This allows you to dynamically modify the user experience based on their assignment.

Note: If you are using the AdBlocker feature, ensure you replace __ssobj with the specific path configured for your site.

Initial configuration

Enabling Cookie Support

Cookie support is essential for the Engine API 2.0 to function properly. Be sure to enable cookies on mobile apps and other non-browser environments to maintain consistent user assignments throughout a session and across multiple visits.

For web environments on both mobile and desktop, cookie support is typically enabled by default and requires no additional configuration.

User Agent Header for API Calls

When making calls to the Engine API 2.0, ensure you include the User-Agent header of the requesting device or application. This header is essential for accurate tracking and assignment.

Disabling Robot Detection

Make sure that all calls to the Engine API 2.0 include a header to disable robot detection to maintain consistent tracking and response accuracy across API requests.

Your SiteSpect site needs to be configured to support a Robot Detection Header. When this header is present, SiteSpect does not perform its usual bot check. (Applies to both ARD and IAB.)

If your site does not include this configuration, contact your customer success team.

Disabling Skip Assignment When First Hit Is Internal Content

The new Engine API 2.0 is not compatible with the Skip Assignment When First Hit Is Internal Content feature at this time.

Example API Request with Payload

Here’s an example of a POST call to the Engine API 2.0 to retrieve assignments, variations, and metrics. This example includes a request payload to provide context for triggering variations and metrics.

POST /__ssobj/static/endpoint.json

Payload:

{
  "user-status": "logged-in",
  "view-name": "product-details",
  "user-action": "add-to-cart"
}

Example API Response

The response from the API provides a detailed breakdown of the user’s campaign assignments, variations, metrics, user information, and payload:

{
    "context": "sitespect_endpoint",
    "site": 696,
    "assignments": [
        {
            "testCampaignId": "6349",
            "testCampaignName": "Mobile App New PDP",
            "variationGroupId": "169754",
            "variationGroupName": "New Version"
        }
    ],
    "variations": [
        {
            "variationGroupId": "169754",
            "variationId": "221488",
            "variationName": "New Image Viewer"
        },
        {
            "variationGroupId": "169754",
            "variationId": "221489",
            "variationName": "New Add to Cart Modal"
        }
    ],
    "metrics": [
        {
            "metricId": "221464",
            "metricName": "Mobile App Screen View"
        },
        {
            "metricId": "221498",
            "metricName": "Mobile App User Logged-In"
        },
        {
            "metricId": "221473",
            "metricName": "Mobile App Add to Cart"
        }
    ],
    "userInfo": {
        "userGuid": "G7428972397518143528",
        "visitCount": "7",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36 PB",
        "geo": {
            "country": "United States",
            "region": "Massachusetts",
            "city": "Boston",
            "latitude": "42.360",
            "longitude": "-71.058"
        }
    },
    "payload": {
        "discountOffer": "10% off",
        "bannerColor": "#ff5733"
    }
}

Breakdown of the API Response

1. Assignments

Use the assignments section to determine which campaigns and variation groups the user is assigned to. This helps you control which variations are shown to the user in your A/B testing and feature flagging scenarios.

Example:

    "assignments": [
        {
            "testCampaignId": "6349",
            "testCampaignName": "Mobile App New PDP",
            "variationGroupId": "169754",
            "variationGroupName": "New Version"
        }
    ]

2. Variations

This section is optional and allows for more granular adjustments within a variation group. Use variations to control which specific changes are displayed based on user segments and app context. Variations are triggered based on the data in the API request payload.

Example:

    "variations": [
        {
            "variationGroupId": "169754",
            "variationId": "221488",
            "variationName": "New Image Viewer"
        },
        {
            "variationGroupId": "169754",
            "variationId": "221489",
            "variationName": "New Add to Cart Modal"
        }
    ]

3. Metrics

The metrics section contains details about any metrics captured for the user. Metrics are triggered based on the data exposed in the API request payload.

    "metrics": [
        {
            "metricId": "221464",
            "metricName": "Mobile App Screen View"
        },
        {
            "metricId": "221498",
            "metricName": "Mobile App User Logged-In"
        },
        {
            "metricId": "221473",
            "metricName": "Mobile App Add to Cart"
        }
    ]

4. User Information

The userInfo section provides contextual information about the user.

userGuid: The global unique identifier for the user.
visitCount: The total number of visits by the user.
userAgent: The browser user agent string.
geo: Geolocation details for the user, such as country, region, city, latitude, and longitude.

Example:

    "userInfo": {
        "userGuid": "G7428972397518143528",
        "visitCount": "7",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36 PB",
        "geo": {
            "country": "United States",
            "region": "Massachusetts",
            "city": "Boston",
            "latitude": "42.360",
            "longitude": "-71.058"
        }
    }

4. Payload

Use the payload section to pass additional key-value pairs that provide dynamic data for updating your application in real-time. These attributes allow you to customize the user experience based on specific user properties, experiment data, or contextual information defined within the SiteSpect UI.

Example:

    "payload": {
        "discountOffer": "10% off",
        "bannerColor": "#ff5733"
    }

Customizing the Engine API Response

The Engine API 2.0 offers extensive customizability, allowing the response format to be tailored on a per-site basis for maximum flexibility. This means you can define the exact data structure format exposed in the API response. This customizable approach ensures that the API seamlessly adapts to your workflow, making it easier to deliver personalized experiences, manage feature flags, and conduct targeted A/B tests.