Skip to content
This repository
branch: master

- Typos

- Removed comments/suggestions recommendation until we define a strategy for this. Github issue tracker works well for now.
latest commit 137a955e84
Henry Porter authored December 19, 2013
Octocat-spinner-32 LandingPageReferrerStandard Add landing page referrer standard December 11, 2012
Octocat-spinner-32 README.md - Typos December 19, 2013
README.md

We've moved!

We've been working hard to update the Universal Variable Specification. Version 1.1.1 (January 2013 release) is frozen below - if you've been directed here by one of our technology partners, be aware their documentation may refer to this version.

Otherwise, visit our new Universal Data Layer microsite which includes:

  • Our latest specification and release notes
  • A useful validation tool to flag up issues in your code
  • Best practice guides and support

http://tools.qubitproducts.com/uv/developers/

Qubit Universal Variable Specification

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.1.1"
    ...
}

Implementation Hints

DO:

  • Read the specification carefully and make sure you know exactly what value to store against each key. Because our specification is very wide-ranging, you may find similar (but different) properties under different keys - for example, a Product’s unit_price does not include discounts, but its unit_sale_price does.
  • Use valid JSON: this includes enclosing strings in quotes and avoiding trailing commas. You may find it helpful to use an online tool such as JSONLint.com to validate your code.
  • Use the correct JavaScript object types as defined in the specification - for example, prices should always be unquoted JavaScript numbers.
  • Declare window.universal_variable as high up in the page as possible, above Qubit Opentag or any other third party tracking tool, so that other code can use your universal variable.
  • Include the Universal Variable version number in your JavaScript code, so you can be prepared for future updates to the Universal Variable standard.

DON’T:

  • Instantiate more parts of the Universal Variable object than you need - for instance, there is probably no need to declare a completed Transaction on your site’s home page.
  • Re-declare the whole Universal Variable when you only want to add to the existing window.universal_variable object, or you’ll lose what has already been declared!
  • Omit mandatory fields, such as a LineItem’s Quantity field.
  • Omit additional fields required in the specification: for example, to declare a Product’s unit_sale_price, its currency must also be declared.

A word on privacy

This standard includes methods to represent personal data, such as users' names and addresses. Like many other parts of the standard, inclusion of this information is optional.

Before you implement universal variable, decide which personal information you wish to include. Then, ensure you only include personal information where necessary, for example:

  • a User object (including the user's name) could be populated in pages served to a signed-in user
  • a Transaction object (including a postal address) could be populated in a confirmation or receipt page, served to a customer on completion of a retail transaction.

Why include personal data in universal variable?

The intention of this standard is to reproduce information that may already be displayed on-screen in a more machine-readable format for a better user experience, not to disclose personal information to anyone who shouldn't see it. Remember that any data in universal variable will only be accessible by scripts loaded on that particular page, and the use of personal data falls under your applicable data protection laws as normal.

The universal_variable object

universal_variable can contain any of the following properties:

JSON key Type Describes
user User object The visitor or logged in user.
page Page object The page currently being viewed.
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 possible. Even if the current user is not signed in, there could still be useful information such as their returning status or preferred language.

  • 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.1"
}

Universal Variable Object Definitions

Page

The Page object describes the current page.

Properties (all optional):

Property JSON Key Type Description
Page Category category String A short description of the type of page, e.g. 'home', 'product', 'category', 'search', 'basket', 'checkout', 'confirmation'. The page's position in the site hierarchy should not be used in this field, however it could be used as the subcategory.
Page Subcategory subcategory String A short description of the instance of this type of page, e.g. 'landing', 'checkout-stage1'. Site hierarchies can be used, e.g. 'Womens - Shoes - Running Shoes'.
Use only if a category has been defined.
System Environment environment String A name for the environment which is creating this Universal Variable data, e.g. 'development', 'testing', 'production'.
Page Variation variation String If serving multiple versions of this page during testing, specify a variation name. e.g. 'original','newstyle'
Page Revision revision String If a site's pages implement versioning, state a revision here, e.g. '1.1'.

For example:

window.universal_variable = {
    "page": {
        "category": "product",                     // the page is of type Product
        "subcategory": "Mens - Shirts - Formal",   // specifically, the Product page for mens formal shirts
        "environment": "production",
        "variation": "Original",
        "revision": "1.1"
    }
}

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.

Properties (all optional):

Property JSON key Type Description
User Real Name name String The user's full name.
User 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.
User Internal ID user_id String A unique identifier that the web site uses internally to identify this user.
User Email Address email String The user's full email address.
User 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.
User Returning Status returning Boolean False if this page view forms part of the user's first visit to this site, True otherwise.
User 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).
User Types types Array of Strings Arbitrary labels to assign to this user, e.g. 'high-value','female'.
User Facebook ID facebook_id Number The user's Facebook User ID, as returned by the Facebook API.
User 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.

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 related to this one through well-defined relationships (e.g. a product in the same range from the same manufacturer), not generated based on the output of recommendation algorithms.
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 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
LineItem Product product Product object Mandatory. The product which has been added to the basket or transaction.
LineItem Quantity quantity Number Mandatory. The number of this product that has been added to the basket or transaction.
LineItem Subtotal subtotal Number Total cost of this LineItem, including tax, excluding shipping and discounts.
LineItem 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.

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": 30.00,
    "total_discount": 5.00
}

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.

Properties:

Property JSON key Type Description
Basket ID id String A unique ID for this basket.
Basket Currency currency String Mandatory. The ISO 4217 code for the currency this basket's costs are denominated in.
Basket Price subtotal Number Mandatory. The cost of the basket, excluding shipping or discounts.
Basket Price Includes Tax subtotal_include_tax Boolean Indicates whether Basket Price includes tax.
Basket Voucher Code voucher String Voucher code entered.
Basket Voucher Discount voucher_discount Number Total amount of discount due to the voucher code entered.
Basket Tax tax Number The amount of tax payable for this basket.
Basket Shipping Cost shipping_cost Number The amount of shipping cost payable for the items in this basket.
Basket Shipping Method shipping_method String Delivery method selected for the items in this basket.
Basket Total total Number The total cost of this basket, including tax, shipping and discounts.
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 = {
    "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.
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'.
Transaction Currency currency String Mandatory. The ISO 4217 code for the currency this transaction's costs are denominated in.
Transaction Payment Type payment_type String Payment method, e.g. 'Visa','PayPal','Voucher'.
Transaction Price subtotal Number The transaction amount, excluding shipping or discounts.
Transaction Includes Tax subtotal_include_tax Boolean Indicates whether Transaction Price includes tax.
Transaction Voucher Code voucher String Voucher code entered.
Transaction Voucher Discount voucher_discount Number Total amount of discount due to the voucher code entered.
Transaction Tax tax Number The amount of tax payable for this transaction.
Transaction Shipping Cost shipping_cost Number The amount of shipping cost payable for this transaction.
Transaction Shipping Method shipping_method String Delivery method selected for this transaction.
Transaction Total total Number Mandatory. The total cost of this transaction, including tax, shipping and discounts.
Transaction Delivery Address delivery Address object Delivery address for this transaction.
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
Listing Search Query query String If the products are search results, the query that was entered.
Listing Items items Array of Product objects The products which have been displayed to the user on this page.

Example:

window.universal_variable = {
    "listing": {
        "query": "shoes on sale",
        "items": [Product, Product, Product, ...]
    }
}

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

The Event object identifies when something has just happened, either since the last page view, or during the current page view.

Properties:

Property JSON key Type Description
Event Type type String Label for the type of event that's taken place, e.g. 'conversion','signup'.
Event Time time String String representation of the time at which this event occurred.
Event Cause cause String Description of what caused this event, e.g. 'idle for 5 minutes'.
Event Effect effect String Description for any user-facing activity that happens as a result of this event, e.g. 'popup shown'.

Example:

window.universal_variable = {
    "events": [{
        "type": "newsletter_signup",
        "cause": "checkout_popup"
    }]
}

Journey

The Journey object is used as part of a travel-related Product, representing a single 'leg' of travel.

Properties:

Property JSON key Type Description
Journey Type type String Label for the type of journey, e.g. 'flight','train'.
Journey Name name String Short description of this journey, e.g. 'Flight BA456 from JFK'.
Journey Code code String Unique identifier for this journey, e.g. an Amadeus or Sabre code.
Journey Time time String ISO 8601 representation of the date and/or time of travel.
Journey Adult Count adults Number Number of adults travelling.
Journey Child Count children Number Number of children travelling.
Journey Infant Count infants Number Number of infants travelling.

Example:

window.universal_variable = {
    "product": {
        "journeys": [{
        "type": "flight",
        "name": "Flight BA123 from London Heathrow",
        "code": "FLIGHTCODE123",
        "time": "2012-09-01 09:00",
        "adults": 2,
        "children": 2,
        "infants": 0
        }]
    }
}

Accommodation

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

Properties:

Property JSON key Type Description
Accommodation Type type String Label for the type of accommodation, e.g. 'hotel'.
Accommodation Name name String Short description, e.g. 'New York, Algonquin Hotel'.
Accommodation Code code String Unique identifier, e.g. a reservation system code.
Accommodation Checkin Time checkin_time String ISO 8601 representation of the date and/or time of checkin.
Accommodation Checkout Time checkout_time String ISO 8601 representation of the date and/or time of checkout.
Accommodation Adult Count adults Number Number of adults travelling.
Accommodation Child Count children Number Number of children travelling.
Accommodation 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",
        "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
}
Something went wrong with that request. Please try again.