Ecommerce Integration Documentation Version 1.0 (BETA)

Introduction

This guide describes how to send ecommerce (cart/order) data to your VBOUT account.

Getting Started

Overview

There are two types of ecommerce data you can send:
  1. Cart Data
    Represents the cart and its product items
  2. Order Data
    Represents the successful order/purchase
  3. Intent Data
    Represents the shopper's interest in products and categories

Enable Ecommerce Tracking

To enable VBOUT ecommerce tracking plugin, go to your VBOUT Account's settings page, Website Tracking Code option, and find domain settings. Activate the e-commerce tracking under the "Domain Settings". Once the settings is enabled, you can start using the ecommerce code below to send cart and order data to your VBOUT account.

1. Include the script in your web-page:
<script src="https://www.vbout.com/ext/plugin.ecommerce.js"></script>
2. Create instance of VboutEcommerce and pass your VBOUT's domain account code and the options you want.

	var vboutEcommerceAccount = 'VBT-XXXXXX-XXXXX'; // Your VBOUT domain account
	var vboutEcommerceOptions = {
		ip: '10.20.30.40', // Set the IP for the Shopper
		uniqueid: 'as75-98df-6wer-cd36' // Set the unique identify for the Shopper
	};

	// Create instance of VboutEcommerce
	var vboutEcommerce = new VboutEcommerce(vboutEcommerceAccount, vboutEcommerceOptions);

Implementation

You can implement ecommerce tracking while the user is adding an item on the shopping cart or once the user has successfully completed the checkout process.

_vbset.push(["COMMAND", {
	// data to be passed to VBOUT's Ecommerce Tracking account
}]);
vboutEcommerce.command("COMMAND", { // data to be passed to VBOUT's Ecommerce Tracking account });

Tracking Anonymous Shoppers Versus Customers

VBOUT uses 3 different values to map the site visits, engagement and orders between your visitor's shopping cart and your VBOUT account.

These values are listed in the priority below:
  1. Emails Address of the shopper - (Primary identifier)
  2. Unique Shopper ID or "uniqueid" (Which can be set by you) - (Secondary identifier)
  3. Shopper's IP Address (Automatically detected by the VBOUT tracker) - (Tertiary network identifier)

Each time you send a PUSH call to VBOUT, you can pass along the Email and/or Unique Shopper ID (uniqueid) to map the history of the shopper to that PUSH call. If you do not have the email, the system will label this shopper as Anonymous and will use the "uniqueid" and IP to merge the data to one profile. If the "uniqueid" is not provided, the detected IP address will be used.

Consider the following case scenarios:
  1. A shopper visits 10 products on a phone then completes the purchase using the same device, providing an email during checkout. VBOUT will merge the 10 products visited to his newly created customer profile.
  2. If that same shopper uses a different device instead on the same network IP to checkout, VBOUT will read a different "uniqueid" and will not merge the history from his previous phone visits, unless you pass the same "uniqueid" used on his phone to the new device, inside the PUSH call.
  3. Any repeat engagement or purchases thereafter, using that same customer email, will be merged with the customer's existing profile on VBOUT, regardless of the "uniqueid" or network IP.
  4. If a different shopper on the same network IP makes a purchase using a different email address, the system will create a completely different customer profile on VBOUT.
  5. If you do not pass a "uniqueid" to VBOUT, the system will use the detected network IP to merge the activities to one profile under that one IP address, even if the visits were from two different people on the same network IP.
_vbset.push(["COMMAND", {
	"uniqueid": "13ee8a4b4076a4d3c9dbbd976c6f767f", // identify request source
}]);
vboutEcommerce.command("COMMAND", { "uniqueid": "13ee8a4b4076a4d3c9dbbd976c6f767f", // identify request source });

Sync Cart Data

Adding Cart Item

Once the plugin is enabled, it creates a transparent shopping cart object. You can now add items to your shopping cart object.

All products should be sent together each time in order to update your cart in your VBOUT's account.

Cart Item Object

Cart Item object contains the following values:

Key Value Type Required Description
cartid text Yes The cart ID. This ID is what links items to the cart they belong (e.g. 1234)
productid text Yes The product ID. The unique ID of the item (e.g. 123)
name text Yes The item name (e.g. Navy Sweatshirt)
description text - The item description (e.g. This Navy Sweatshirt fits all sizes.)
variation object - (e.g. {"color": "red"})
price currency Yes The individual, unit, price for each item (e.g. 11.99)
discountprice currency - The individual, unit, discount price for each item (e.g. 10.99)
currency currency - The currency for each item (e.g. USD)
quantity integer Yes The number of units purchased in the transaction (e.g. 2)
sku text - Specifies the SKU or item code (e.g. SKU12)
categoryid text - The category ID to which the item belongs (e.g. 19)
category text - The category name to which the item belongs (e.g. Clothing)
link text - The link url of the product item (e.g. https://domain.com/clothing/product/123)
image text - The image url of the product item (e.g. https://domain.com/images/product-123.jpg)

The following code should be repeated for each product in your cart.

_vbset.push(["store.cart.item", {
	"cartid": "123456", //Cart ID [Required]
	"productid": "22",	//Product ID [Required]
	"name": "Fluffy Pink's Bunnies", //Product name [Required]
	"price": "11.99", //Unit price [Required]
	"discountprice": "10.99", //Unit discount price
	"currency": "$", // Unit currency
	"quantity": "1", //Quantity [Required]
	"variation": {"Color": "Red", "Size": "XL"}, //Variation
	"sku": "DD23444", //SKU/code.
	"categoryid": "cat-123", //Category or variation ID.
	"category": "Party Toys", //Category or variation name.
	"link": "http://domain.com/product.php?id=123456",
	"image": "http://domain.com/uploads/products/123456.jpg"
}]);
vboutEcommerce.command("store.cart.item", { "cartid": "123456", //Cart ID [Required] "productid": "22", //Product ID [Required] "name": "Fluffy Pink's Bunnies", //Product name [Required] "price": "11.99", //Unit price [Required] "discountprice": "10.99", //Unit discount price "currency": "$", // Unit currency "quantity": "1", //Quantity [Required] "variation": {"Color": "Red", "Size": "XL"}, //Variation "sku": "DD23444", //SKU/code. "categoryid": "cat-123", //Category or variation ID. "category": "Party Toys", //Category or variation name. "link": "http://domain.com/product.php?id=123456", "image": "http://domain.com/uploads/products/123456.jpg" });

For Example:

_vbset.push(["store.cart.item", {
	"cartid": "123456",
	"productid": "22",
	"name": "Fluffy Pink's Bunnies",
	"price": "11.99",
	"quantity": "1"
}]);
_vbset.push(["store.cart.item", { "cartid": "123456", "productid": "23", "name": "Fluffy Bunny Backpack SD00055", "price": "15.99", "quantity": "1" }]);
_vbset.push(["store.cart.item", { "cartid": "123456", "productid": "25", "name": "Pink fluffy bunny slippers", "price": "9.99", "quantity": "1" }]);
_vbset.push(["store.cart.item", { "cartid": "123456", "productid": "27", "name": "Fluffy Pink Rabbit Ears", "price": "5.99", "quantity": "1" }]);
vboutEcommerce.command("store.cart.item", { "cartid": "123456", "productid": "22", "name": "Fluffy Pink's Bunnies", "price": "11.99", "quantity": "1" });
vboutEcommerce.command("store.cart.item", { "cartid": "123456", "productid": "23", "name": "Fluffy Bunny Backpack SD00055", "price": "15.99", "quantity": "1" });
vboutEcommerce.command("store.cart.item", { "cartid": "123456", "productid": "25", "name": "Pink fluffy bunny slippers", "price": "9.99", "quantity": "1" });
vboutEcommerce.command("store.cart.item", { "cartid": "123456", "productid": "27", "name": "Fluffy Pink Rabbit Ears", "price": "5.99", "quantity": "1" });

Sending Cart Details

Send the data once you have configured all your ecommerce data in the shopping cart. This command will sync cart data to your VBOUT account.

"customer" should be sent with cart's details to link this cart to this customer in your VBOUT's account

Cart Details Object

Cart Details object contains the following values:

Key Value Type Required Description
cartid text Yes The cart ID. This ID is what links items to the cart they belong (e.g. 1234)
storename text - The name of the store from which this transaction occurred (e.g. Acme Clothing)
abandonurl text - The cart's abandon url link when the user dose not proceed with the purchase (e.g. http://domain.com/cart.php?c=abandonurl)
customer text - Customer email address (e.g. john@smith.com)
uniqueid text - a unique user identifier that won't change (browser session for example) (e.g. 13ee8a4b4076a4d3c9dbbd976c6f767f)
_vbset.push(["store.cart.send", {
	"cartid": "123456", //Cart ID [Required]
	"customer": "john@smith.com", // customer's email address
	"storename": "My Store", // Store name
	"abandonurl": "http://domain.com/cart.php?c=sampleabandonurl" //Abandon cart link.
}]);
vboutEcommerce.command("store.cart.send", { "cartid": "123456", //Cart ID [Required] "customer": "john@smith.com", // customer's email address "storename": "My Store", // Store name "abandonurl": "http://domain.com/cart.php?c=sampleabandonurl" //Abandon cart link. });

Clearing Cart Details

You can manually clear the shopping cart data.

_vbset.push(["store.cart.clear"]);
vboutEcommerce.command("store.cart.clear");

Sync Order Data

Sending Order Details

When a user completes an order, you can use this command to sync order details.

This command will sync order to your VBOUT's account once you have configured all order data.

Order Details Object

Order Data contains the following values:

Key Value Type Required Description
cartid text Yes The cart ID. This ID is what links items to the cart they belong (e.g. 1234)
orderid text Yes The order ID. The unique ID of the successful order/purchase (e.g. 12345)
orderdate timestamp - The order date. Date should be in Unix timestamp format (e.g. 1531537877))
paymentmethod text Yes The payment method used (e.g. Mastercard)
shippingmethod text - The shipping method used (e.g. Fedex)
shippingcost float - The shipping cost (e.g. 10.00)
storename text - The name of the store from which this transaction occurred (e.g. Acme Clothing)
grandtotal float Yes The final amount after tax cost, discounts, and other fees are added up. (e.g. 105.99)
subtotal float - The total amount without the tax, discounts, and other fees. (e.g. 45.44)
promocode text - The promo name/code (e.g. the-offer)
promovalue float - The promo cost (e.g. 5.00)
discountcode text - The discount name/code (e.g. 10off)
discountvalue float - The discount value (e.g. 10.00)
taxname text - The tax name/code (e.g. Value Added Tax)
taxcost float - The tax cost (e.g. 5.00)
otherfeename text - The other fee name/code (e.g. Handling Fee)
otherfeecost float - The other fee cost (e.g. 5.00)
currency text - The currency used to purchase. (e.g. USD )
status text - The status of the purchase. (e.g. In Progress)
notes text - The notes of the order. (e.g. A note for order)
customerinfo object Yes The customer's information.
billinginfo object - The order's billing information.
shippinginfo object - The order's shipping information.

Order Customer Object

Order Customer Object contains the following values:

Key Value Type Required Description
firstname text - Customer first name (e.g. John)
lastname text - Customer last name (e.g. Smith)
email text Yes Customer email address (e.g. john@smith.com)
phone text - Customer phone number (e.g. 1-800-123-1234)
company text - Customer company name (e.g. MyCompany Ltd.)

Order Billing Object

Order Billing Object contains the following values:

Key Value Type Required Description
firstname text - Billing first name (e.g. John)
lastname text - Billing last name (e.g. Smith)
email text - Billing email address (e.g. john@smith.com)
phone text - Billing phone number (e.g. 1-800-123-1234)
company text - Billing company name (e.g. MyCompany Ltd.)
address text - Billing address (e.g. 1601 Willow Road)
address2 text - Billing address (Line 2) (e.g. Menlo Park)
city text - Billing city (e.g. New York)
statename text - Billing State name (e.g. California)
statecode text - Billing State code (e.g. CA)
countryname text - Billing Country name (e.g. United States)
countrycode text - Billing Country code (e.g. US)
zipcode text - Billing postal code (e.g. 94205)

Order Shipping Object

Order Shipping Object contains the following values:

Key Value Type Required Description
firstname text - Shipping first name (e.g. John)
lastname text - Shipping last name (e.g. Smith)
email text - Shipping email address (e.g. john@smith.com)
phone text - Shipping phone number (e.g. 1-800-123-1234)
company text - Shipping company name (e.g. MyCompany Ltd.)
address text - Shipping address (e.g. 1601 Willow Road)
address2 text - Shipping address (Line 2) (e.g. Menlo Park)
city text - Shipping city (e.g. New York)
statename text - Shipping State name (e.g. California)
statecode text - Shipping State code (e.g. CA)
countryname text - Shipping Country name (e.g. United States)
countrycode text - Shipping Country code (e.g. US)
zipcode text - Shipping postal code (e.g. 94205)
_vbset.push(["store.order.send", {
	"cartid": "123456", //Cart ID [Required]
	"orderid": "12", //Order ID [Required]
	"paymentmethod": "Mastercard",	//Payment method [Required]
	"grandtotal": 100.00, //Grand total amount [Required]
	"orderdate": "1531454869", //Order Date in timestamp.
	"shippingmethod": "Fedex", //Shipping method
	"shippingcost": 55.55,	//Shipping cost
	"subtotal": 70.00, //Sub-total amount.
	"discountcode": "10off",	//Discount name/code
	"discountvalue": 10.00,	//Discount  amount
	"promocode": "5off",	//Promo code
	"promovalue": 5.00,	//Promo amount
	"taxname": "", //Tax name/code
	"taxcost": 0.00, //Tax amount
	"otherfeename": "handling fee",	//Other fees name
	"otherfeecost": 3.00,	//Other fees amount
	"currency": "USD",	//Currency.
	"status": "In Progress",	// Order Status.
	"notes": "A note for order",	// Order Notes.
	"storename": "My Store",
	"customerinfo": {
		"firstname": "John",	//Customer first name.
		"lastname": "Smith",	//Customer last name
		"email": "john@smith.com",	//Customer email address [Required]
		"phone": "1-800-123-1234",	//Customer phone number.
		"company": "MyCompany Ltd.",	//Customer company name.
	},
	"billinginfo": {
		"firstname": "John", //Billing first name
		"lastname": "Smith", //Billing last name
		"email": "john@smith.com",	//Billing email address
		"phone": "1-800-123-1234",	//Billing phone number
		"company": "MyCompany Ltd.",	//Billing company name
		"address": "1601 Willow Road",	//Billing address
		"address2": "Menlo Park",	//Billing address (Line 2)
		"city": "New York", //Billing city.
		"statename": "California",	//Billing State name
		"statecode": "CA",	//Billing State code
		"countryname": "United States",	//Billing Country name
		"countrycode": "US",	//Billing Country code
		"zipcode": "94205", //Billing postal code
	},
	"shippinginfo": {
		"firstname": "John", //Shipping first name
		"lastname": "Smith", //Shipping last name
		"email": "john@smith.com",	//Shipping email address
		"phone": "1-800-123-1234",	//Shipping phone number
		"company": "MyCompany Ltd.",	//Shipping company name
		"address": "1601 Willow Road",	//Shipping address
		"address2": "Menlo Park",	//Shipping address (Line 2)
		"city": "New York", //Shipping city
		"statename": "California",	// Shipping State name
		"statecode": "CA",	// Shipping State code
		"countryname": "United States",	// Shipping Country name
		"countrycode": "US",	// Shipping Country code
		"zipcode": "94205", // Shipping postal code
	}
}]);
vboutEcommerce.command("store.order.send", { "cartid": "123456", //Cart ID [Required] "orderid": "12", //Order ID [Required] "paymentmethod": "Mastercard", //Payment method [Required] "grandtotal": 100.00, //Grand total amount [Required] "orderdate": "1531454869", //Order Date in timestamp. "shippingmethod": "Fedex", //Shipping method "shippingcost": 55.55, //Shipping cost "subtotal": 70.00, //Sub-total amount. "discountcode": "10off", //Discount name/code "discountvalue": 10.00, //Discount amount "promocode": "5off", //Promo code "promovalue": 5.00, //Promo amount "taxname": "", //Tax name/code "taxcost": 0.00, //Tax amount "otherfeename": "handling fee", //Other fees name "otherfeecost": 3.00, //Other fees amount "currency": "USD", //Currency. "status": "In Progress", // Order Status. "notes": "A note for order", // Order Notes. "storename": "My Store", "customerinfo": { "firstname": "John", //Customer first name. "lastname": "Smith", //Customer last name "email": "john@smith.com", //Customer email address [Required] "phone": "1-800-123-1234", //Customer phone number. "company": "MyCompany Ltd.", //Customer company name. }, "billinginfo": { "firstname": "John", //Billing first name "lastname": "Smith", //Billing last name "email": "john@smith.com", //Billing email address "phone": "1-800-123-1234", //Billing phone number "company": "MyCompany Ltd.", //Billing company name "address": "1601 Willow Road", //Billing address "address2": "Menlo Park", //Billing address (Line 2) "city": "New York", //Billing city. "statename": "California", //Billing State name "statecode": "CA", //Billing State code "countryname": "United States", //Billing Country name "countrycode": "US", //Billing Country code "zipcode": "94205", //Billing postal code }, "shippinginfo": { "firstname": "John", //Shipping first name "lastname": "Smith", //Shipping last name "email": "john@smith.com", //Shipping email address "phone": "1-800-123-1234", //Shipping phone number "company": "MyCompany Ltd.", //Shipping company name "address": "1601 Willow Road", //Shipping address "address2": "Menlo Park", //Shipping address (Line 2) "city": "New York", //Shipping city "statename": "California", // Shipping State name "statecode": "CA", // Shipping State code "countryname": "United States", // Shipping Country name "countrycode": "US", // Shipping Country code "zipcode": "94205", // Shipping postal code } });

Clearing Order Details

Manually clear the order data.

_vbset.push(["store.order.clear"]);
vboutEcommerce.command("store.order.clear");

Sync Intent Data

Adding Search Details

When a user search for a product, you can use below command to send his search term details to your VBOUT's account.

"customer" should be sent with search's details to link this search to this customer in your VBOUT's account

Product Search Object

Search Data contains the following values:

Key Value Type Required Description
query text Yes Search Query (e.g. iPhone)
customer text - Customer email address (e.g. john@smith.com)
uniqueid text - a unique user identifier that won't change (browser session for example) (e.g. 13ee8a4b4076a4d3c9dbbd976c6f767f)
_vbset.push(["store.product.search", {
	"query": "iPhone", // Search query [Required]
	"customer": "john@smith.com" // customer's email address
}]);
vboutEcommerce.command("store.product.search", { "query": "iPhone", // Search query [Required] "customer": "john@smith.com" // customer's email address });

Adding Product View

When a user visit/view product page, you can use below command to send his visit details to your VBOUT's account.

"customer" should be sent with product's details to link this visit/view to this customer in your VBOUT's account

Product View Object

Product Data contains the following values:

Key Value Type Required Description
customer text - Customer email address (e.g. john@smith.com)
uniqueid text - a unique user identifier that won't change (browser session for example) (e.g. 13ee8a4b4076a4d3c9dbbd976c6f767f)
productid text Yes The product ID. The unique ID of the product (e.g. 123)
name text Yes The product name (e.g. Navy Sweatshirt)
price currency Yes The individual, unit, price for the product (e.g. 11.99)
discountprice currency - The individual, unit, discount price for the product (e.g. 10.99)
currency currency - The currency for the product (e.g. USD)
sku text - Specifies the SKU or product code (e.g. SKU12)
categoryid text - The category ID to which the product belongs (e.g. 19)
category text - The category name to which the product belongs (e.g. Clothing)
link text - The link url of the product item (e.g. https://domain.com/clothing/product/123)
image text - The image url of the product item (e.g. https://domain.com/images/product-123.jpg)
description text - The product description (e.g. This Navy Sweatshirt fits all sizes.)
_vbset.push(["store.product.view", {
	"customer": "john@smith.com", // customer's email address
	"productid": "22",	//Product ID [Required]
	"name": "Fluffy Pink's Bunnies", //Product name [Required]
	"price": "11.99", //Unit price [Required]
	"discountprice": "10.99", //Unit discount price
	"currency": "$", // Unit currency
	"sku": "DD23444", //SKU/code.
	"categoryid": "cat-123", //Category or variation ID.
	"category": "Party Toys", //Category or variation name.
	"link": "http://domain.com/product.php?id=123456",
	"image": "http://domain.com/uploads/products/123456.jpg"
}]);
vboutEcommerce.command("store.product.view", { "customer": "john@smith.com", // customer's email address "productid": "22", //Product ID [Required] "name": "Fluffy Pink's Bunnies", //Product name [Required] "price": "11.99", //Unit price [Required] "discountprice": "10.99", //Unit discount price "currency": "$", // Unit currency "sku": "DD23444", //SKU/code. "categoryid": "cat-123", //Category or variation ID. "category": "Party Toys", //Category or variation name. "link": "http://domain.com/product.php?id=123456", "image": "http://domain.com/uploads/products/123456.jpg" });

Adding Category View

When a user visit/view category page, you can use below command to send his visit details to your VBOUT's account.

"customer" should be sent with category's details to link this visit/view to this customer in your VBOUT's account

Category View Object

Category Data contains the following values:

Key Value Type Required Description
customer text - Customer email address (e.g. john@smith.com)
uniqueid text - a unique user identifier that won't change (browser session for example) (e.g. 13ee8a4b4076a4d3c9dbbd976c6f767f)
categoryid text Yes The category ID. The unique ID of the category (e.g. cat-123)
name text Yes The category name (e.g. Clothing)
link text - The link url of the category (e.g. https://domain.com/clothing/cat-123)
image text - The image url of the category (e.g. https://domain.com/images/category-cat-123.jpg)
description text - The category description (e.g. Clothing fits all sizes.)
_vbset.push(["store.category.view", {
	"customer": "john@smith.com", // customer's email address
	"categoryid": "cat-123", //Category ID [Required]
	"name": "Party Toys", //Category name [Required]
	"link": "http://domain.com/category.php?id=cat-123",
	"image": "http://domain.com/uploads/category/cat-123.jpg"
}]);
vboutEcommerce.command("store.category.view", { "customer": "john@smith.com", // customer's email address "categoryid": "cat-123", //Category ID [Required] "name": "Party Toys", //Category name [Required] "link": "http://domain.com/category.php?id=cat-123", "image": "http://domain.com/uploads/category/cat-123.jpg" });

Update Customer Preferences

You can use below command to update the Customer Preferences in your VBOUT's account.

Customer Preferences Object

Customer Preferences contains the following values:

Key Value Type Required Description
customer text Yes Customer email address (e.g. john@smith.com)
categories array - The unique IDs of the preferred/selected categories for the customer (e.g. ["cat-123", "cat-456", "cat-789"])
_vbset.push(["store.customer.preferences", {
	"customer": "john@smith.com", // customer's email address [Required]
	"categories": ["cat-123", "cat-456", "cat-789"] //Category IDs
}]);
vboutEcommerce.command("store.customer.preferences", { "customer": "john@smith.com", // customer's email address [Required] "categories": ["cat-123", "cat-456", "cat-789"] //Category IDs });