Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master

This branch is 0 commits ahead and 0 commits behind master

Fetching latest commit…

Cannot retrieve the latest commit at this time

README.md

QuBit Universal Variable Specification Version 1.1.0

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 the string "1.1.0" to indicate that this version of the specification is being used.

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

Implementation Considerations

This universal_variable JSON object must be created before any browser scripts that try to access it. It is imperative to use this structure, as this ensures that the values are present on the page when a script tries to access them. If the variables are created further down the page, they will not be picked up.

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 EventList object Identifies events that have just occurred.
version String Which version of this standard is being used, currently '1.1.0'.

Only declare what's necessary

The universal variable object should be declared lazily: only include a property if it's actually necessary.

If a web site does not implement product recommendations, the window.universal_variable.recommendation object should not even be declared.

The same applies to properties of objects. For example, if a page has categories but not subcategories, simply leave out the 'subcategory' property, do not declare it with any value.

A very simple example of a universal_variable object would be:

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

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.

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 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. 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.

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.

Example:

{
    "product": {
            "url": "http://www.example.com/product?=ABC123", 
            "name": "ABC Trainers",
            "unit_price": 30.00
            "currency": "GBP"
        },
    "quantity": 1,
    "subtotal": 30.00
}

Basket

The Basket object describes the current state of the a user's shopping basket or cart.

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. If possible, this object should only be present when the transaction has just been completed and is no longer modifiable.

Properties:

Property JSON key Type Description
Transaction ID order_id String A unique ID for this transaction.
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"
        }, ...]
    }
}

EventList

The Eventlist object wraps an array of Event objects.

Properties:

Property JSON key Type Description
EventList Items items Array of Event objects The events which have happened since the last page view, or during the current page view.

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": [{
        "name": "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
        }]
    }
}
Something went wrong with that request. Please try again.