JSON variable tracking format

Elements needed for each page type are added for illustration.

• Elements are mandatory unless marked otherwise.
• All values are assumed to be JSON strings unless otherwise noted.
• 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

The following elements are common to all page tracking requests.

type

Type of page. The type of the page determines the message format. The following are valid page types:

• attribute
• basket
• brand
• category
• checkout
• home
• order
• other
• product
• searchresults
• wishlist

lang

Language code. See the list of commerce language codes that Optimizely Recommendations uses.

user (optional)

For example:

"user" : {…}

📘

Note

When you provide user, also supply id. Use id instead of name and email as they are deprecated and kept for backward compatibility only.

• email – (Optional) Deprecated. The email address of the customer. For example:
  JSON

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

• id – (Optional) Pseudonymised ID of the user. For example:
  JSON

  "id" : "abcd1234efgh"
  

  This identifies the user in the Optimizely Recommendations system. Use the user ID to improve tracking and recommendations. You can also use it in other Optimizely products, such as mail and triggers.
  To prevent losing user behavior, you must send an up-to-date mapping between email addresses and pseudonymized user IDs. You only need to provide this once so Optimizely Recommendations can replace existing customer email addresses with their corresponding pseudonymized user ID.

channel (optional)

Access channel. If you omit channel, web is assumed. The following are the available values:

• web
• mobileweb

abTestContent (optional)

Controls how much A/B test information to return in the info callback. If you omit abTestContent, no A/B testing information is returned. The following are the available values:

• summary – Only the test name and A/B group are returned in the response.
• full – All available A/B group information is returned in the response.

For more information on this element, see A/B testing.

recContent (optional)

Recommendation content configuration. If you omit recContent, full is assumed. The following are the available values:

• full – Returns full product details (like 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.

customAttributes (optional)

Allows real-time filtering of recommendations based on the specified custom attributes. Custom attributes are only used in real-time; they are not stored in the system. They provide additional context on the page event that you can use to manipulate the recommendations that Optimizely returns.

• Must be a comma-separated list of attribute names and values.
• Attribute names must contain no spaces.
• You can add any variable you want in the customAttributes element.

"customAttributes" : {  
                       "customerType" : "XL",  
                       "userLocale"   : "en_GB",  
                       "userSegment"  : "gold"  
                     }

Use case for custom attributes

You can use custom attributes to filter recommendations based on the segment a user belongs to. For example, if user A belongs to segment A, they may be limited to only seeing products from catalog A. To ensure user A does not get recommended products from catalog B, you can indicate the user's segment by passing user A with a custom attribute of userSegment=“A” in the JSON tracking request. You can then create a segment-matching rule with this information (like userSegment=productSegment).

Using custom attributes requires each product in the feed to have an attribute that indicates what segment a product belongs to. If product A belongs to segment A, then in the previous rule, Optimizely can recommend product A to user A. If product B only belongs to catalog B, then user A would never see product B in their recommendations. This process ensures that Optimizely only returns the appropriate recommendations to each user.

customer (optional)

Used for business-to-business (B2B) customers. Customer is an all-encompassing object in the tracking model which contains information based on a client's customer.

• (Optional) Ensure that your object in the tracking message is populated correctly by stating the customerId and segmentIds so the customer can view them in your system.
• Set up the feed to associate the products with the segmentIds that are associated with 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 lets you handle your customers in the tracking request, as shown in the following code.

{  
  "customer" : {  
                 "customerId" : "someCustomerId",  
                 "segmentIds" : [  
                                  "someSegmentId",  
                                  "someOtherSegmentId"  
                                ]  
               }  
}

You can only define the following variables in the customer element:

• customerID – Identifies your customer. Must be unique.
• segmentIDs – A list of segment IDs to which your customer belongs. Map these identifiers according to how you deal with data segregation. This field maps to the segment IDs associated with products in the feed configuration. Segments in this list allow for optional filtering against the product segment IDs.

Add customAttributes or customer elements (optional)

You can add the customAttributes and customer elements to any page tracking request within the outermost curly brackets of each page's tracking script.

An example of adding a customAttributes element to the order page tracking request:

{
  "type": "order",
  "lang": "en-gb",
  "order": {
    "orderNo": "ABC-DE-123456",
    "items": [{
        "refCode": "PROD500",
        "qty": 2,
        "price": 25.5
      },
      {
        "refCode": "PROD600",
        "qty": 4,
        "price": 12.0
      }
    ],
    "currency": "GBP",
    "subtotal": 99.0,
    "shipping": 3.0,
    "total": 102.0
  }
  "customAttributes": {
    "customerType": "XL",
    "userLocale": "en_GB",
    "userSegment": "gold"
  }
}

An example of adding a customer element to the product page tracking request:

{
  "type": "product",
  "lang": "en-gb",
  "product": { "refCode": "PROD500" }
  "customer": {
    "customerId": "someCustomerId",
    "segmentIds": [
      "someSegmentId",
      "someOtherSegmentId"
    ]
  }
}