Qubit API

This is for:

Developer

Intro

Qubit provides a number of APIs and data sources to deliver integrated personalizations. The Qubit API is a single interface to fetch, mutate, and deliver data using the most succinct and performant mechanism possible.

GraphQL

Qubit has a razor-sharp focus on the performance of services, especially those requested from end-user devices, which can be anywhere in the world, with variable internet connections.

The Qubit API makes use of GraphQL, a query language originally developed by Facebook. This allows the data required for personalization to be requested in one go and ensures only the fields explicitly required are returned.

This is more performant than multiple requests to REST endpoints as not only is there a single HTTP call, the response payload will return just the data points requested rather than the full dataset–this reduces network bandwidth, which is key on slower connections, such as mobile devices.

Accessing GraphiQL UI

GraphQL comes with a UI that can be used to interactively explore the schema and write test queries. This can be found here.

Each field is documented within the GraphQL schema and can be explored in the Documentation Explorer. You can open this by selecting Docs in the upper-right hand corner of the page and then selecting into a query or field.

Example Queries

Visitor Location

Query

query ($trackingId: String!, $contextId: String!) {
  property(trackingId: $trackingId) {
    visitor(contextId: $contextId) {
      location {
        city
        country
      }
    }
  }
}

Variables

{
  "trackingId": "retail_demo_union_fashion",
  "contextId": "jm18y1783bc-0jqqm7bbb-erdi26o"
}

Where:

  • trackingId is the Id for your property

  • contextId is the identifier for a visitor–on web this is the value of _qubitTracker cookie.

Segments and recommendations

One of the key advantages of GraphQL is that it allows you to get different types of data in a single request. In the below example, the list of segments a visitor belongs to is fetched along with some product recommendations:

Query

query ($trackingId: String!, $contextId: String!, $strategy: String!) {
  property(trackingId: $trackingId) {
    visitor(contextId: $contextId) {
      segments {
        memberships {
          segmentId
        }
      }
      productRecommendations(strategy: [{name: $strategy}], items: 2) {
        strategy
        product {
          name
          url
          images {
            url
          }
          categories {
            name
          }
          currency
          unitPrice
          unitSalePrice
          additionalFields
        }
      }
    }
  }
}

Variables

{
  "trackingId": "retail_demo_union_fashion",
  "contextId": "jm18y1783bc-0jqqm7bbb-erdi26o",
  "strategy": "popular"
}

@qubit/qubit-api package

To make the Qubit API as easy as possible to use, an NPM package called @qubit/qubit-api has been created for use in experiences. This can be found in the package picker in app.qubit.com and is documented here.