Server experiences API reference

This is for:

Developer

In this article, we’ll show you how you can use the Server Experiences API to deliver personalizations.

Unique values

Before using the Server Experiences API, you will require the following unique values:

Name Description

<tracking_id>

Qubit tracking Id for the property the request is made from. This will be provided by your CSM

Get experiences

Request

Called via a GET request:

GET https://sse.qubit.com/v1/{trackingId}/experiences?contextId={contextId}&experienceIds={experienceIds}&{preview}&variation={variation}&ignoreSegments

Where:

  • contextId is a user Id. This could be a user’s Qubit context Id, held in the _qubitTracker cookie, or a userId of your choice

Note

If this value is not provided then one will be generated and returned in the response. This helps solve a particular use case where you would like to set up a server experience for a first-time visitor on a landing page, and the visitor’s context Id is not yet present in the _qubitTracker cookie.

  • experienceIds is a comma-separated list of experience Ids, which is used to filter results to show only those experiences. If any of the provided Ids are not found, the API will return a 404 error

Warning

You cannot GET archived experiences. If you provide the Id of an archived experience in your request, we will return a 404 error. For more about archiving experiences, see Archive experiences.

  • preview if present, the latest unpublished iteration for each experience will be used, instead of the latest published iteration

  • variation is an optional parameter to specify the experience variation to return. Intended to be used for previewing what the API returns for each of the different variations, this must be an integer and will apply a filter to return only the variation of an experience that matches this Id. This is based on the variation master Id

  • ignoreSegments is an optional parameter, which, when set, will result in payloads for all experiences being returned regardless of the segment specification of the experience

Example:

https://sse.qubit.com/v1/miquido/experiences?contextId=9ad614fcef3c5443](https://sse.qubit.com/v1/miquido/experiences?contextId=9ad614fcef3c5443)

Response

The response is an array called experiencePayloads with a JSON object for each experience.

Warning

The payload will only be returned for those experiences that the user is segmented for.

 
{
    "experiencePayloads": [
        {
            "payload": JSON,
            "isControl": boolean,
            "id": int,
            "callback": URL,
            "variation": int
        }
    ]
}

Each experience is an object with 5 fields:

  • payload is a JSON object containing the fields that were set in the Qubit app, for the variation that the given context Id has been bucketed into. This should be passed through to the developer as a key/value object for them to consume and use inside the view to set component attributes in the app

  • isControl is a boolean, stating whether or not the given context Id falls into the control group of the experience. Provided for advanced use cases - should be passed to a developer for evaluation

  • id is the experience Id, provided for advanced use cases–should be passed to a developer for evaluation

  • callback is the callback URL to be invoked with a POST request containing a JSON object with a field called id with the value of the deviceId. This must always be invoked when an experience is shown, even if the visitor is in the control group. This call can be abstracted away by the SDK

  • variation is Id of the variation that the payload was extracted from. This is the variation master Id. Provided for advanced use cases–should be passed to a developer for evaluation

Note

In addition, two more fields will be returned, contextId and cookieDomains. In the scenario when no contextId was provided in the original request, one will be generated. On web channels, this should be set in a cookie called _qubitTracker on the most appropriate domain listed in cookieDomains. This cookie should be set on the response of the page load so it exists before the Qubit scripts load on the client.

callback

Included with the response for each experience is a callback URL. This needs to be called whenever the user sees the experience. This tells the system to start tracking the goals for the experience, based on the users experiences, and records that the user saw the experiences.

Request

The actual request will be very similar to the following example.

POST https://sse.qubit.com/v1/callback?data=6QGAeyJFeHBlcmllbmNlSWQiOjEzOTczMSwiSXRlcmF0aW9uARUsMzc3NDE0LCJWYXJpFRUUODU1NjEyHRUUTWFzdGVyATCYODI2OTg3LCJJc0NvbnRyb2wiOmZhbHNlLCJUcmFmZmljQWxsb2NhAV9EIjowLjUsIlByb2JhYmlsaXR5ARJgNjc2MjU4MjI2OTMyMTE3MywiUGlkIjowLkYZABhUZW1wbGF0Bb0QbnVsbCwBZEhja2luZ0lkIjoibWlxdWlkbyJ9
Warning

The URL needs to be taken from the experience object as shown in the previous example request.

Response

The response will be a 200 in all cases.