Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
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
Failed to load latest commit information.
LandingPageReferrerStandard Add landing page referrer standard
README.md - Typos

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 keyTypeDescribes
userUser objectThe visitor or logged in user.
pagePage objectThe page currently being viewed.
productProduct objectThe product being shown on this page, if a single product is being displayed.
basketBasket objectThe state of the visitor's basket at the time this page was served.
transactionTransaction objectA transaction that has just completed (if this is the first page view served to the user since they completed the transaction).
listingListing objectMultiple products that are present on a page, excluding recommendations (e.g. search results, or a product category page).
recommendationRecommendation objectProducts that are recommended to the user on this page.
eventsArray of Event objectsContains the events that have occurred on the page.
versionStringWhich 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):

PropertyJSON KeyTypeDescription
Page CategorycategoryStringA 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 SubcategorysubcategoryStringA 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 EnvironmentenvironmentStringA name for the environment which is creating this Universal Variable data, e.g. 'development', 'testing', 'production'.
Page VariationvariationStringIf serving multiple versions of this page during testing, specify a variation name. e.g. 'original','newstyle'
Page RevisionrevisionStringIf 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):

PropertyJSON keyTypeDescription
User Real NamenameStringThe user's full name.
User Login NameusernameStringThe identifier that the user provides to log in to the site (the 'username').
Use only if a category has been defined.
User Internal IDuser_idStringA unique identifier that the web site uses internally to identify this user.
User Email AddressemailStringThe user's full email address.
User Preferred LanguagelanguageStringThe 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 StatusreturningBooleanFalse if this page view forms part of the user's first visit to this site, True otherwise.
User Transacted Statushas_transactedBooleanTrue 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 TypestypesArray of StringsArbitrary labels to assign to this user, e.g. 'high-value','female'.
User Facebook IDfacebook_idNumberThe user's Facebook User ID, as returned by the Facebook API.
User Twitter IDtwitter_idStringThe 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

PropertyJSON keyTypeDescription
Product IDidStringA unique identifier for the product, that is used by the web site only, i.e. not necessarily a Stock Keeping Unit (SKU) Code.
Product URLurlStringA canonical URL for this product.
Product NamenameStringName of the product.
Product DescriptiondescriptionStringBrief description of the product.
Product ManufacturermanufacturerStringName of the manufacturer for this product.
Product CategorycategoryStringA short description of this type of product, e.g. 'shoes', 'package holiday'.
Product SubcategorysubcategoryStringA 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 Productslinked_productsArray of Product objectsProducts 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 CurrencycurrencyStringThe ISO 4217 code for the currency used for this product's prices.
Product Priceunit_sale_priceNumberThe 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 Promotionsunit_priceNumberThe 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 ReviewsreviewsArray of Review objectsReviews that have been written (by customers or staff) about this Product.

Additional properties for products requiring stock keeping

PropertyJSON keyTypeDescription
Product SKU Codesku_codeStringThe Stock Keeping Unit (SKU) code for the product.
Product Stock RemainingstockNumberThe quantity of this product remaining in stock (zero for out-of-stock).

Additional properties for products with promotions

PropertyJSON keyTypeDescription
Product Voucher CodevoucherStringA 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

PropertyJSON keyTypeDescription
Product ColorcolorStringThe currently selected color of this product.
Product SizesizeStringThe 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.

PropertyJSON keyTypeDescription
JourneysjourneysArray of Journey objectsDescriptions of the flights, trains, or other journeys included in this product.
AccommodationsaccommodationsArray of Accommodation objectsDescriptions 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:

PropertyJSON keyTypeDescription
LineItem ProductproductProduct objectMandatory. The product which has been added to the basket or transaction.
LineItem QuantityquantityNumberMandatory. The number of this product that has been added to the basket or transaction.
LineItem SubtotalsubtotalNumberTotal cost of this LineItem, including tax, excluding shipping and discounts.
LineItem Total Discounttotal_discountNumberThe 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:

PropertyJSON keyTypeDescription
Basket IDidStringA unique ID for this basket.
Basket CurrencycurrencyStringMandatory. The ISO 4217 code for the currency this basket's costs are denominated in.
Basket PricesubtotalNumberMandatory. The cost of the basket, excluding shipping or discounts.
Basket Price Includes Taxsubtotal_include_taxBooleanIndicates whether Basket Price includes tax.
Basket Voucher CodevoucherStringVoucher code entered.
Basket Voucher Discountvoucher_discountNumberTotal amount of discount due to the voucher code entered.
Basket TaxtaxNumberThe amount of tax payable for this basket.
Basket Shipping Costshipping_costNumberThe amount of shipping cost payable for the items in this basket.
Basket Shipping Methodshipping_methodStringDelivery method selected for the items in this basket.
Basket TotaltotalNumberThe total cost of this basket, including tax, shipping and discounts.
Basket Itemsline_itemsArray of LineItem objectsThe 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:

PropertyJSON keyTypeDescription
NamenameStringFull name of the recipient.
AddressaddressStringStreet address (excluding city, state, postcode, country).
CitycityStringCity.
StatestateStringState (Two-letter abbreviation if a US state)
PostcodepostcodeStringThe postal code or ZIP code.
CountrycountryStringCountry, 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:

PropertyJSON keyTypeDescription
Transaction IDorder_idStringA unique ID for this transaction.
Transaction Returning StatusreturningBooleanFalse 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 CurrencycurrencyStringMandatory. The ISO 4217 code for the currency this transaction's costs are denominated in.
Transaction Payment Typepayment_typeStringPayment method, e.g. 'Visa','PayPal','Voucher'.
Transaction PricesubtotalNumberThe transaction amount, excluding shipping or discounts.
Transaction Includes Taxsubtotal_include_taxBooleanIndicates whether Transaction Price includes tax.
Transaction Voucher CodevoucherStringVoucher code entered.
Transaction Voucher Discountvoucher_discountNumberTotal amount of discount due to the voucher code entered.
Transaction TaxtaxNumberThe amount of tax payable for this transaction.
Transaction Shipping Costshipping_costNumberThe amount of shipping cost payable for this transaction.
Transaction Shipping Methodshipping_methodStringDelivery method selected for this transaction.
Transaction TotaltotalNumberMandatory. The total cost of this transaction, including tax, shipping and discounts.
Transaction Delivery AddressdeliveryAddress objectDelivery address for this transaction.
Transaction Billing AddressbillingAddress objectBilling address for this transaction.
Basket Itemsline_itemsArray of LineItem objectsThe 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:

PropertyJSON keyTypeDescription
Listing Search QueryqueryStringIf the products are search results, the query that was entered.
Listing ItemsitemsArray of Product objectsThe 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:

PropertyJSON keyTypeDescription
Recommendation ItemsitemsArray of Product objectsThe 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:

PropertyJSON keyTypeDescription
Event TypetypeStringLabel for the type of event that's taken place, e.g. 'conversion','signup'.
Event TimetimeStringString representation of the time at which this event occurred.
Event CausecauseStringDescription of what caused this event, e.g. 'idle for 5 minutes'.
Event EffecteffectStringDescription 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:

PropertyJSON keyTypeDescription
Journey TypetypeStringLabel for the type of journey, e.g. 'flight','train'.
Journey NamenameStringShort description of this journey, e.g. 'Flight BA456 from JFK'.
Journey CodecodeStringUnique identifier for this journey, e.g. an Amadeus or Sabre code.
Journey TimetimeStringISO 8601 representation of the date and/or time of travel.
Journey Adult CountadultsNumberNumber of adults travelling.
Journey Child CountchildrenNumberNumber of children travelling.
Journey Infant CountinfantsNumberNumber 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:

PropertyJSON keyTypeDescription
Accommodation TypetypeStringLabel for the type of accommodation, e.g. 'hotel'.
Accommodation NamenameStringShort description, e.g. 'New York, Algonquin Hotel'.
Accommodation CodecodeStringUnique identifier, e.g. a reservation system code.
Accommodation Checkin Timecheckin_timeStringISO 8601 representation of the date and/or time of checkin.
Accommodation Checkout Timecheckout_timeStringISO 8601 representation of the date and/or time of checkout.
Accommodation Adult CountadultsNumberNumber of adults travelling.
Accommodation Child CountchildrenNumberNumber of children travelling.
Accommodation Infant CountinfantsNumberNumber 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:

PropertyJSON keyTypeDescription
Review BodybodyStringBody of this review.
Review RatingratingStringHow 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.