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": "[email protected]",
		"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
}