HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

JSON variable tracking format

Describes the structure common to all pages.

Elements needed for each page type are added for illustration.

  • Elements are mandatory unless the [Optional] tag is present.
  • All values are assumed to be JSON strings, except where the [Number] tag is used (all numbers are 64-bit integers, such as a Java Long data type).
  • The [String] tag explicitly identifies the JSON data type.
  • Indentation and extra whitespaces in JSON response examples are added for readability of JSON data in this document; spaces are not required in the actual JSON responses.

Elements common to all request types.

Name Descriptions and usage
type Type of page.

The type of the page determines the message format. Valid page types are the following:
lang Language code.

See Language codes.
user [Optional]

For example:

"user" : {…}

Note: When you provide user, also supply id. Use id instead because name and email are deprecated and kept for backward compatibility.

  • email

    [Deprecated] [Optional]

    The email address of the customer. For example:

    "name"  : "John Customer",
    "email" : "[email protected]"
  • id


    Pseudonymised ID of the user. For example:

    "id" : "abcd1234efgh"
    This identifies the user in the Personalization system. Use the user ID to improve tracking and recommendations; you can use it also in other Optimizely products, such as Mail and Triggers.

    Note: For Product Recommendations, to prevent user behavior from being lost, you need to send us an up-to-date mapping between email addresses and pseudonymized user IDs. This only needs to be provided once so that Optimizely Personalization can replace existing customer email addresses with their corresponding pseudonymized user ID.

channel [Optional]

Access channel.

Available values are:
  • web
  • mobileweb

Note: If omitted, web is assumed.

abTestContent [Optional]

Controls how much A/B test information to return in the info callback.

Available values are:
  • full Only the test name and A/B group are returned in the response.
  • summary All available A/B group information is returned in the response.
See A/B testing for more information.

Note: If this attribute is omitted, no A/B Testing information is returned.

recContent [Optional]

Recommendation content configuration.

Available values are:
  • full. Returns full product details (such as, price, image, title, URL). 
  • refCodeOnly. Returns a list of elements containing only product reference codes and recommendation IDs. (This is commonly used if stock or prices change frequently, and you want to reference the database for verification before rendering recommendations.)

Note: If omitted full is assumed.

customAttributes [Optional]

Allows real-time filtering of recommendations based on the specified custom attributes.

A comma-separated list of attribute names and values. Attribute names must contain no spaces.

"customAttributes" : { 
                       "customerType" : "XL",
                       "userLocale"   : "en_GB", 
                       "userSegment"  : "gold"
Custom attributes are only used in real-time; they are not stored in the system.
customer [Optional]

Used for B2B customers, customer is an all-encompassing object in the tracking model which contains information based on a client's customer.
  • You can optionally ensure that your object in the tracking message is populated correctly, stating the customerId and segmentIds so the customer can view in your system.
  • Set the feed up to associate the products with the segmentIds that are associated to the product.
  • When you provide this data, filter recommendations later in the process and show only recommended products from a user's segment.
  • You can additionally filter using the marketsegment expression. For example: u.marketsegment = "roofing"
    • u.marketsegment. Matches all market segments of the current session from tracking.
    • r.marketsegment. Matches all market segments for the recommended product from the catalog.
    • p.marketsegment. Matches all market segments of currently viewed product (segments from the catalog).
As of version 1.4, a new field in the tracking request allows for the handling of your customers in the tracking request, as shown in the following code.

  "customer" : {
                 "customerId" : "someCustomerId",
                 "segmentIds" : [
  • customerID Identifies your customer. (Must be unique.)
  • segmentIDs A list of segmentIds to which your customer belongs. Map these identifiers according to how you deal with data segregation. This field maps to the segmentId's associated with products in the feed configuration. Segments in this list allow for optional filtering against the product segment ids.