Go to Qubit

Universal Variable documentation

UV Specification Version 1.2.1

Qubit Universal Variable is our suggested way to structure the data presented on your pages. With Qubit Universal Variable, our aim is to help you easily access the pieces of data you need on your pages from your containers.

Namespace

Our namespace is window.universal_variable.*:

Example:

window.universal_variable = {};

Version

Set this to indicate that this version of the specification is being used.

window.universal_variable = {
  "version" : "1.2.1"
  ...
}

Release notes

The universal_variable object

universal_variable can contain any of the following properties:

JSON key Type Describes
page Page object The page currently being viewed.
user User object The visitor or logged in user.
product Product object The product being shown on this page, if a single product is being displayed.
basket Basket object The state of the visitor’s basket at the time this page was served.
transaction Transaction object A transaction that has just completed (if this is the first page view served to the user since they completed the transaction).
listing Listing object Multiple products that are present on a page, excluding recommendations (e.g. search results, or a product category page).
recommendation Recommendation object Products that are recommended to the user on this page.
events Array of Event objects Contains the events that have occurred on the page.
version String Which version of this standard is being used.

Which Universal Variable properties should be populated?

For each page, declare those parts of the Universal Variable that make up your visitor’s browsing experience at that time.

  • DO Include the User object wherever the user information is available. even if the current user is not signed in.

  • DO Include the basket page wherever possible: this includes pages where the basket is not the main feature of the page, such as product, category or home pages.

  • DON’T Instantiate several fields with ‘null’ or empty strings if you don’t have a value to populate them with. For example, if you don’t know a user’s Facebook ID, there’s no need to include that field in the User object at all. Similarly, if a web site does not implement product recommendations, the window.universal_variable.recommendation object should not even be declared.

A very simple example of a universal_variable object would be:

window.universal_variable = {
  "user": {
    "returning": true
  },
  "page": {
    "category": "home"
  },
  "version": "1.1.2"
}

Universal Variable Object Definitions

Page

This object describes the current page. It’s primary use is to categorise the pageview into useful buckets that will make analytics and optimization simpler – enabling you to deal with meaningful categories rather than raw URLs in your data.

Property JSON Key Type Description
Type type String

What type of page this is from an ecommerce funnel perspective. Useful for analysis on targeting, for example fire this tag on all checkout or product pages.

We strongly recommend home, category, product, basket, checkout or confirmation for a traditional retail site. For other verticals, such as travel, you may need some customisation.

Breadcrumb breadcrumb Array

Multi-level categorisation of the current page in the site hierarchy, presented as an array where element 0 is the highest level category and the final element is the most granular (often the title of current page). On many sites this will reflect the website’s navigational breadcrumb, though without the first “Home” element.

This categorisation should be implemented consistantly across the site.

No need to include the breadcrumb property where there is no hierarchy, such as on the home page.

System Environment environment String A name for the environment which is creating this Universal Variable data, e.g. ‘development’, ‘testing’, ‘production’.
The page object has been updated since 1.1.1, with the category and subcategory strings deprecated in place of page.type and page.breadcrumb.

For example, a category page three levels deep:

window.universal_variable = {
  "page": {
    "type" : "category",
    "breadcrumb" : [
      "suits",
      "single breasted suits",
      "oxford"
    ],
    "environment": "production"
  }
}

A blog page:

window.universal_variable = {
  "page": {
    "type" : "content",
    "breadcrumb" : [
      "The Fashion Blog",
      "London Fashion Week '13",
      "Behind the scenes at the River Island fashion show"
    ],
    "environment": "production"
  }
}

Payment details page of the checkout:

window.universal_variable = {
  "page": {
    "type" : "checkout",
    "breadcrumb" : [
      "Payment Details"
    ],
    "environment": "production"
  }
}

Home page:

window.universal_variable = {
  "page": {
    "type" : "home",
    "environment": "production"
  }
}

User

The User object describes the current user of the web site. This object should be populated whether or not the user is logged in – populate as much as possible. If the user is not logged in, you’ll probably only be able to populate the user.language attribute.

Properties (include what you have available):

Property JSON key Type Description
Real Name name String The user’s full name.
Login Name username String The identifier that the user provides to log in to the site (the ‘username’).

Use only if a category has been defined.
Internal ID user_id String A unique identifier that the web site uses internally to identify this user.
Email Address email String The user’s full email address.
Preferred Language language String The user’s preferred language, must be an IETF compatible string, e.g. ‘en-us’, ‘en-gb’. IETF codes start with an ISO 639-1 language
representation, and are extensible by region.
Returning Status returning Boolean False if this page view forms part of the user’s first visit to this site, True otherwise.
Transacted Status has_transacted Boolean True if this user has completed a transaction at any time in the past (i.e. earlier in this visit, or during a previous visit).
Facebook ID facebook_id Number The user’s Facebook User ID, as returned by the Facebook API.
Twitter ID twitter_id String The user’s Twitter ID.

Example:

window.universal_variable = {
  "user": {
    "name": "Example User",
    "username": "exampleuser123",
    "user_id": "8492834083",
    "email": "user@example.com",
    "language": "en-gb",
    "returning": true,
    "types": ["high-value","female"]
    "facebook_id": 12345678901232345,
    "twitter_id": "myid"
  }
}

Product

The Product object describes a single product.

This object can:

  • Be a property of the universal_variable object, where one product is displayed on the page.
  • Be used as part of another Product object to denote linked products (see below).
  • Form part of the Listing object if several products are present on the page.
  • Form part of the Recommendation object if the page contains product recommendations.
  • Form part of the LineItem object as part of a transaction or basket.

There are many possible types of product on the Web – here, we first list properties which could reasonably apply to any product, and then list additional properties which could be declared for certain kinds of product. In any case, the properties listed below are all optional.

If visitors are changing their product selection dynamically in a single pageview, you’ll want to update Universal Variable to reflect the change in the state of the page’s data model.

Properties common across most products

Property JSON key Type Description
Product ID id String A unique identifier for the product, that is used by the web site only, i.e. not necessarily a Stock Keeping Unit (SKU) Code.
Product URL url String A canonical URL for this product.
Product Name name String Name of the product.
Product Description description String Brief description of the product.
Product Manufacturer manufacturer String Name of the manufacturer for this product.
Product Category category String A short description of this type of product, e.g. ‘shoes’, ‘package holiday’.
Product Subcategory subcategory String A short description of this type of product, with more granularity than the category, e.g. ‘trainers’.
Use only if a category has been defined.
Product Linked Products linked_products Array of Product objects Products with a direct relationship to this product (not those generated by recommendation algorithms).

Use for products that represent a bundle (where this product object is the bundle, and linked_products are the potential combinations of sub-products).

Product Currency currency String The ISO 4217 code for the currency used for this product’s prices.
Product Price unit_sale_price Number The price for a single unit of this product actually paid by a customer, taking into account any sales and promotions. Note: If a promotion involves selling the same product with different prices in the same transaction (e.g. ten units of a product are in a basket, where the first two receive a 10% discount, and the rest are discounted by 20%), implement the ‘least discounted’ version of the product using this Product object, and implement the further discount by using the `total_discount` property of the LineItem object, which forms part of Baskets and Transactions.Requires Product Currency to be declared.
Product Price Excluding Promotions unit_price Number The price of a single unit of this product, not taking into account discounts and promotions. Requires Product Currency and Product Price to be declared.
Product Odds odds Number The odds of a bet on a gambling site. All odds should be passed as a decimal to 2 decimal places, e.g. for a 3/2 odds, 1.50 should be used.
Product Reviews reviews Array of Review objects Reviews that have been written (by customers or staff) about this Product.

Additional properties for products requiring stock keeping

Property JSON key Type Description
Product SKU Code sku_code String The Stock Keeping Unit (SKU) code for the product.
Product Stock Remaining stock Number The quantity of this product remaining in stock (zero for out-of-stock).

Additional properties for products with promotions

Property JSON key Type Description
Product Voucher Code voucher String A voucher code that has been entered by the user which changes the price of this product. If the user’s voucher is not product-specific, it should instead be applied to the Transaction object after a transaction has been completed.

Additional properties for products that have variations chosen by the user

Property JSON key Type Description
Product Color color String The currently selected color of this product.
Product Size size String The currently selected size of this product.

Additional properties for travel-related products

As before, if some properties are not known at the current stage in a user’s journey, such as checkin and checkout dates, simply do not declare them.

Property JSON key Type Description
Journeys journeys Array of Journey objects Descriptions of the flights, trains, or other journeys included in this product.
Accommodations accommodations Array of Accommodation objects Descriptions of the accommodation stays included in this product.

See the following example of a populated Product object:

{

  "id": "ABC123",
  "sku_code": "123",
  "url": "http://www.example.com/product?=ABC123", 
  "name": "XYZShoes",
  "description": "most popular shoes in our shop",
  "manufacturer": "Acme Corp",
  "category": "Shoe",
  "subcategory": "Trainers",
  "linked_products": [Product, Product, Product, ...],
  "color": "WHITE",
  "size": "M",
  "stock": 10,
  "unit_price": 123.00,
  "unit_sale_price": 100.00,
  "currency": "GBP",
  "voucher": "MYVOUCHER"
}

LineItem

The LineItem object describes a quantity of Products. Arrays of LineItems are used as part of a Basket or Transaction.

Properties:

Property JSON key Type Description
Product product Product object Mandatory. The product which has been added to the basket or transaction.
Quantity quantity Number Mandatory. The number of this product that has been added to the basket or transaction.
Subtotal subtotal Number Total cost of this LineItem, including tax, excluding shipping and discounts.
Total Discount total_discount Number The total discount applied when buying the specified quantity of this product (taking into account any quantity-specific product offers, such as ‘buy one get one free’). The total amount paid for this LineItem should be Subtotal – Total Discount.
Shipping method shipping_method String Optional. Usually shipping_method is declared on a basket level, however if it is possible to select different shipping methods for different products in a transaction, then shipping_method should be declared here instead.
Shipping cost shipping_cost String Optional. Only add if the logic above applies.

Example:

{
  "product": {
      "url": "http://www.example.com/product?=ABC123", 
      "name": "ABC Trainers",
      "unit_price": 30.00,
      "unit_sale_price": 25.00,
      "currency": "GBP"
    },
  "quantity": 1,
  "subtotal": 25.00,
  "total_discount": 5.00,
  "shipping_method": "Royal Mail 1st Class",
  "shipping_cost": 4.99
}

Basket

The Basket object describes the current state of the a user’s shopping basket or cart. It should be populated on any web page that displays basket information – this may include ‘home’, ‘product’ or ‘category’ pages, as well as pages that provide a detailed basket listing.

Ensure the basket object is available across your site to allow for triggering of personalisations based on basket values.

Properties:

Property JSON key Type Description
Basket ID id String A unique ID for this basket.
Currency currency String Mandatory. The ISO 4217 code for the currency this basket’s costs are denominated in.
Subtotal subtotal Number Mandatory. The cost of the basket, excluding shipping or discounts.
Price Includes Tax subtotal_include_tax Boolean Indicates whether Basket Price includes tax.
Voucher Codes vouchers Array Optional. The voucher code(s) that have been applied to the basket. Note there is a distinction between vouchers and promotions, see the difference in the promotions section below.
Voucher Discount voucher_discount Number Optional. Total amount of discount due to the voucher code(s) entered.
Promotion codes promotions Array Optional. The promotion code(s) that have been applied to the basket. Note that we class promotions as codes that are automatically applied to a customer’s basket, rather than a user-inputted code.
Promotion Discount promotion_discount Number Optional. Total amount of discount due to the promotion code(s) applied.
Shipping Cost shipping_cost Number The amount of shipping cost payable for the items in this basket.
Shipping Method shipping_method String Delivery method selected for the items in this basket.
Total total Number The total cost of this basket, including tax, shipping and discounts.
Items line_items Array of LineItem objects The items (and their quantities) present in the basket. One LineItem per distinct product.

Example:

window.universal_variable = {
  "basket": {
    "id": "BASKET2203",
    "currency": "GBP",
    "subtotal": 123.00,
    "subtotal_include_tax": true,
    "tax": 12.00,
    "shipping_cost": 1.00,
    "shipping_method": "Standard Mail",
    "total": 123.00,
    "line_items": [LineItem, LineItem, LineItem, ...]
  }
}

Address

The Address object is used for billing and shipping information in the Transaction object.

Properties:

Property JSON key Type Description
Name name String Full name of the recipient.
Address address String Street address (excluding city, state, postcode, country).
City city String City.
State state String State (Two-letter abbreviation if a US state)
Postcode postcode String The postal code or ZIP code.
Country country String Country, using the two-letter ISO 3166-1 alpha 2 standard.

Example:

{

  "name": "My Name",
  "address": "234 High Street",
  "city": "London",
  "state": "London",
  "postcode": "SW1 1AB",
  "country": "GB"
}

Transaction

The Transaction object describes a completed purchase, and could be displayed on a confirmation or receipt page.

Properties:

Property JSON key Type Description
Transaction ID order_id String A unique ID for this transaction.
Returning Status returning Boolean False if this is the first time a user has been served this Transaction, i.e. it has just happened. True if this Transaction has happened some time ago and its details are being reviewed. For example, the Transaction object on a page served
to a user when they have just completed a purchase should read ‘False’, but if the user returns to this page, for example when clicking a link sent in a confirmation email, it should read ‘True’.
Currency currency String Mandatory. The ISO 4217 code for the currency this transaction’s costs are denominated in.
Payment Type payment_type String Payment method, e.g. ‘Visa’,’PayPal’,’Voucher’.
Price subtotal Number The transaction amount, excluding shipping or discounts.
Includes Tax subtotal_include_tax Boolean Indicates whether Transaction Price includes tax.
Voucher Codes vouchers Array Optional. The voucher code(s) that have been applied to the purchase. Note there is a distinction between vouchers and promotions, see the difference in the promotions section below.
Voucher Discount voucher_discount Number Optional. Total amount of discount due to the voucher code(s) entered.
Promotion codes promotions Array Optional. The promotion code(s) that have been applied to the purchase. Note that we class promotions as codes that are automatically applied to a customer’s basket, rather than a user-inputted code.
Promotion Discount promotion_discount Number Optional. Total amount of discount due to the promotion code(s) applied.
Tax tax Number The amount of tax payable for this transaction.
Shipping Cost shipping_cost Number The amount of shipping cost payable for this transaction.
Shipping Method shipping_method String Delivery method selected for this transaction.
Total total Number Mandatory. The total cost of this transaction, including tax, shipping and discounts.
Delivery Address delivery Address object Delivery address for this transaction.
Billing Address billing Address object Billing address for this transaction.
Basket Items line_items Array of LineItem objects The items (and their quantities) present in the basket. One LineItem per distinct product.

Example:

window.universal_variable = {
  "transaction": {
    "order_id": "WEB123456",
    "currency": "GBP",
    "subtotal": 123.00,
    "subtotal_include_tax": true,
    "voucher": "MYVOUCHER",
    "voucher_discount": 0.00,
    "tax": 10.00,
    "shipping_cost": 1.00,
    "shipping_method": "Standard Mail",
    "total": 130.00,

    "delivery": {
      "name": "Full Name",
      "address": "234 High Street",
      "city": "London",
      "state": "London",
      "postcode": "SW1 1AB",
      "country": "GB"
    },

    "billing": {
      "name": "Full Name",
      "address": "234 High Street",
      "city": "London",
      "state": "London",
      "postcode": "SW1 1AB",
      "country": "GB"
    },

    "line_items": [LineItem, LineItem, LineItem, ...]
  }
}

Listing

The listing object describes a list of Products, for example as displayed as part of category page or search results page.

Properties:

Property JSON key Type Description Example values
Search Query query String If the products are search results, the query that was entered. red shoes
Items items Array of Product objects The products which have been displayed to the user on this page. [Product, Product, Product ... ]
Result Count result_count Integer Number of results returned by this query. 22
Sort By sort_by String How these results are sorted. A useful signal on a visitor’s purchase intent – are they looking for deals? price_descending
price_ascending
Results layout layout String What layout type the user is seeing results in. list
grid
map

Example:

window.universal_variable = {
  "listing": {
    "query": "shoes on sale",
    "items": [Product, Product, Product, ...],
    "sort_by": "price descending",
    "result_count": 200,
    "layout": "grid"
  }
}

Recommendation

The Recommendation object describes products that have been recommended on a page, based on recommendation algorithms.

Properties:

Property JSON key Type Description
Recommendation Items items Array of Product objects The products which have been recommended to the user on this page.

Example:

window.universal_variable = {
  "recommendation": {
    "items": [
    {
      "url": "http://www.example.com/product?=ABC123", 
      "name": "ABC Trainers"
    },
    {
      "url": "http://www.example.com/product?=DEF123", 
      "name": "DEF Trainers"
    },
    {
      "url": "http://www.example.com/product?=GHI123", 
      "name": "GHI Trainers"
    }, ...]
  }
}

Event

Use events to track interesting visitor behaviours that to be flagged in analytics, or to be reacted to in the browser. See the full introduction to events to see how to push a new event object into the window.universal_variable.events[] array.

Properties:

Property JSON key Type Description Example value
Category category String A collection title than can span multiple actions, such as the vendor of a technology widget, an area of a website or particular goal being affected. registration_funnel
blog_interaction
live_chat_widget
Action action String Unique identifer for an event, labelling what has taken place. quote_generated
whitepaper_downloaded
registration_complete
Custom Property custom String Custom properties as part of the event object that provide metadata on the event, for example the product_id of an item added to basket or title of a white paper the visitor downloaded. “whitepaper_title” : “Summer 13″

“product_sku” : “HFJ232111″

Example:

window.universal_variable = {
  "events": [{
    "category": "registration_funnel",
    "action": "completed_stage_3",
    "product_selected" : "enterprise"
  }]
}
Integrating with Google Analytics

Wish to mirror your Universal Variable events in Google Analytics? Include the following properties in your event to ensure it matches Google’s specification.

The category and action keys map directly to Google’s category and action keys, while GA only supports one custom label and one custom value – ensure to include these to make later integration easy.

Property JSON key Type Description GA equivalent
Label label [optional] String “An optional string to provide additional dimensions to the event data”. opt_label
Value value [optional] Integer “An integer that you can use to provide numerical data about the user event”. Must be an integer. opt_value

Journey

The Journey object is used as part of a travel-related Product, representing a single ‘leg’ of travel. Create a new journey object for each stage of a journey – for example, a package holiday will have an outgoing and returning journey, or perhaps multiple outgoing if a flight change is required at a layover airport.

Properties:

Property JSON key Type Description
Type type String Label for the type of journey, e.g. ‘flight’,’train’.
Name name String Short description of this journey, e.g. ‘Flight BA456 from JFK’.
Code code String Unique identifier for this journey, e.g. an Amadeus or Sabre code. (“BA456″).
Start start String ISO 8601 representation of the date and/or time the journey begins (e.g. flight takeoff).
End end String ISO 8601 representation of the date and/or time the journey is completed (e.g. flight lands).
Provider provider String Who is providing your flight/ferry/train journey? e.g. British Airways or Eurotunnel
Ticket type ticket_type String e.g. first class, second class, economy
Destination destination String e.g. LHW
Origin origin String e.g. JFK
Adult Count adults Number Number of adults travelling.
Child Count children Number Number of children travelling.
Infant Count infants Number Number of infants travelling.

Example:

window.universal_variable = {
  "product": {
    "journeys": [{
      "type": "flight",
      "name": "Flight BA123 from London Heathrow",
      "provider" : "BA",
      "ticket_type" : "first_class",
      "origin" : "LHW",
      "destination" : "JFK",
      "code": "BA123",
      "start": "2012-09-01 09:00",
      "start": "2012-09-01 16:30",
      "adults": 2,
      "children": 2,
      "infants": 0
    }]
  }
}

Accommodation

The Accommodation object is used as part of a travel-related Product.

Similar to the Journey object, it’s best practice to create a new accommodation object for each item of accommodation (e.g. hotel room, apartment … ) included in the product.

Properties:

Property JSON key Type Description
Type type String Label for the type of accommodation, e.g. ‘hotel’.
Name name String Short description, e.g. ‘New York, Algonquin Hotel’.
Code code String Unique identifier, e.g. a reservation system code.
Check-in Time checkin_time String ISO 8601 representation of the date and/or time of checkin.
Check-out Time checkout_time String ISO 8601 representation of the date and/or time of checkout.
Nights nights Integer Nights that this accommodation object is being booked for – may be auto calculated from checkout – checkin times.
Room type room_type String Categorisation of room types as makes sense to your business.
Board board String e.g. half board, full board, bed and breakfast
Star rating star_rating Integer
Provider provider String Company providing the accommodation e.g. hotel company, cruise line company
Adult Count adults Number Number of adults travelling.
Child Count children Number Number of children travelling.
Infant Count infants Number Number of infants travelling.

Example:

window.universal_variable = {
  "product": {
    "accommodations": [{
    "type": "hotel",
    "name": "New York, Algonquin Hotel",
    "code": "BOOKINGCODE123",
    "checkin_time": "2012-09-01",
    "checkout_time": "2012-09-08",
    "nights" : 7,
    "provider" : "Marriott Autograph Collection",
    "board" : "full",
    "star_rating" : 4,
    "adults": 2,
    "children": 2,
    "infants": 0
    }]
  }
}

Review

The Review object models a review of a Product.

Properties:

Property JSON key Type Description
Review Body body String Body of this review.
Review Rating rating String How this review rates the Product. For example, a score such as ’5′.

Example:

{
  "product": {
      "url": "http://www.example.com/product?=ABC123", 
      "name": "ABC Trainers",
      "unit_sale_price": 25.00
      "currency": "GBP",
      "reviews": [ {"body": "These are excellent trainers!", "rating": "5"},
             {"body": "Pretty good", "rating": "4"} ]
    },
  "quantity": 1,
  "subtotal": 30.00,
  "total_discount": 5.00
}

Was this helpful?