Revision as of 19:26, 12 February 2019

Barion Pixel Documentation

The Barion pixel is a snippet of JavaScript code that allows you to track visitor activity on your website. It works by loading a small library of functions which you can use whenever a site visitor takes an action that you want to track (called an event).

In order to implement the pixel, you will need:

access to your website's code base
your pixel's base code and associated IDs (barionPixelID)

Implementation

The Barion pixel is a snippet of JavaScript code that loads a small library of functions you can use to track visitor activity on your website. It relies on Barion cookies. By default, the pixel will track URLs visited, domains visited, and the devices your visitors use. In addition, you can use the pixel's library of functions to track other events that are associated with webshop usage and ecommerce.

Base code

Before you can install the pixel, you will need your pixel's base code.

Figure 1

<script>

  (function(i,s,o,g,r,a,m){i['BarionAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
   })(window, document, 'script', 'http://track.barion.com/bt.js', 'bat');
  
  // initialize the pixel
  bat('init', 'addBarionPixelId', 'barionPixelID');

</script>
<noscript>

  <img height="1" width="1" style="display:none" src="http://track.barion.com/a.gif?__ba_client_id=[Your ClientID goes here]&__ba_website_id=[Your WebsiteID goes here]&__ba_pixel_id=[Your Barion Pixel ID goes here]&ev=PageView&noscript=1"/>

</noscript>

When run, this code will download a library of functions which you can then use for tracking. It also automatically tracks a single PageView conversion by calling the bat() function each time it loads. We recommend that you leave this function call intact.

Installing The Pixel

To install the pixel, we highly recommend that you add its base code between the opening and closing <head> tags on every page where you will be tracking website visitor actions. Most developers add it to their website's persistent header, so it can be used on all pages, but it could be used before the closing body tag (</body>) as well.

Placing the code within your <head> tags reduces the chances of browsers or third-party code blocking the pixel's execution. It also executes the code sooner, increasing the chance that your visitors are tracked before they leave your page.

There are two ways to track conversions with the pixel:

standard events, which are visitor actions that we have defined and that you report by calling a pixel function
custom events, which are visitor actions that you have defined and that you report by calling a pixel function

Standard Events

Standard events are predefined visitor actions that correspond to common, conversion-related activities, such as searching for a product, viewing a product, or purchasing a product. Standard events support parameters, which allow you to include an object containing additional information about an event, such as product IDs, categories, and the number of products purchased.

In order to track an event the event needs to be fired, that is the corresponding event with its properties need to be added inside Your javascript or page. This can be seen on Figure 2 and Figure 3.

Figure 2


var contentViewProperties = {
    'id': 'My blog page',
    'contentType': 'Page',
    'name': 'Very cool product',
}
bat('track', 'contentView', contentViewProperties);

Figure 3

$("#addtocart_button").click(function(){

    // sample product data
    var addToCartPorperties = {
        'id': 'a',
        'contentType': 'Page',
        'name': 'a',
        'ean': 'a',
        'unitPrice': 1000,
        'totalItemPrice': 2000,
        'unit': 'kg',
        'currency': 'huf',
        'quantity': 2,   
    }    

    bat('track', 'addToCart', addToCartPorperties);

});

All standard events are tracked by calling the pixel's bat('track') function, with the event name, and a JSON object as its parameters (sometimes optional). For example, here's a function call to track when a visitor has completed a purchase event, with currency and value included as a parameter. (Figure 2)

Standard event descriptions

With these standard events one can describe a lot of ecommerce related user actions in a meaningful way. Each event have its own set of properties that are needed in order to fully understand and record the users intentions/behaviour.

Table 1: Event descriptions

Event name	Description
setUserProperties	With this event One can add user related information.
contentView	User sees a certain content on a page (e.g. product, article, promotion, banner, etc). When a key page is viewed such as a product page. This event may be fired on pageload.
clickProduct	A click on a product in any list (search, recommendation box, etc). Usually fired at user click
clickProductDetail	A click of product details. (e.g. more info link). Usually fired when user clicks.
customizeProduct	When a person customizes a product. (color, size, etc). Typically fired at user click.
clickPromo	A click on an internal promotion. Fired at mouse click.
addToCart	This event may be fired when a product is added to the shopping cart (users clicks on an add to cart button) upon user clicks.
removeFromCart	This event may be fired when a product is removed to the shopping cart (users clicks on an add to cart button) upon user clicks.
initiateCheckout	This event may be fired when a the user checks out the cart, clicks on the checkout button.
addPaymentInfo	When payment information is added in the checkout flow, this event may be fired upon user click.
initiatePurchase	A person clicks on a purchase button (and possibly enters the Thank You Page).
purchase	When a purchase is made or checkout flow is completed. Successful or unsuccesful. This may be employed on the Thank you page (typically) on pageload.
search	When a search is entered into a search field upon sending the form, this event may be fired.
signUp	To track user signup, when a registration form is completed/sent to the server (just when the status is OK), this event may be fired upon pageload.
grantConsent	User consent is granted for tracking.
revokeConsent	User consent is revoked for tracking.
rejectConsent	User consent is rejected for tracking.
error	If one want to track errors this event may be used for that.

Custom events

Custom events may be defined, with arbitrary text data as parameters. One way to do so is to fire the customEvent event depicted in Figure 4. The event may hold up to 5 attributes: eventCategory, eventAction, eventProperty, eventLabel, eventValue. If You want to add custom properties to standard events You may do so by adding the “_” prefix to that particular event. This is denoted in Figure 5.

Figure 4: Custom event tracking


// sample customData
var customData = {
    eventCategory: 'Video',
    eventAction: 'play',
    eventProperty: 'video',
    eventLabel: 'Fall Campaign',
    eventValue: 42        
}

bat('track', 'customEvent', customData);

Figure 5: Custom event tracking

var contentViewProperties = {
        'id': 'My blog page',
        'contentType': 'Page',
        'name': 'Very cool product',
        '_mycustomparameter': 42
    }

    bat('track', 'contentView', contentViewProperties);

Event Properties

Each event may hold a given set of parameters in order to describe a particular user action. In order to provide complete data some parameters are mandatory/required while some a optional. Properties are given to the event in a standard Javascript object with assigning each property (key) a value.

A value has a value type. Some are primitive types like text, integer and float types and there are two compound types item_list and the address a value type. Only compound types are enforced with validation, primitive types are converted during validation and message sending implicitly if the value type is different from the required value type. Text values are truncated to 1024 characters.

Standard properties

The table here shows all standard properties that are used throughout the tracking. Each property is context sensitive, which means only a handful of properties are needed in each event, and from those only some may be required.

Table 2: Standard properties

name	type	description
id	text	SKU of product/id of article/the promotion ID/etc.
contentType	text	The content type of the page visited. Possible values: Page/Product/Article/Promotion/Banner/Misc. Values here are enforced/validated.
name	text	Full name of product/article/promotion etc (e.g. Android T-Shirt or e.g. Summer Sale)
ean	text	Contains the International Article Number (EAN) when applicable.
brand	text	Brand part of product/brand described in name
category	text	coat\|winter" or "clothes\|coat\|autumn").
variant	text	The variant of the product (e.g. Black)
description	text	The detailed description of the item.
imageUrl	text	A URL pointing to an image that shows the item. E.g. the picture of the product
unit	text	The measurement unit of the item. (e.g. pcs, litre)
unitPrice	float	Price of product (the price of one measurement unit of the item).
totalItemPrice	float	The total price of the item.
currency	text (ISO 4217 format)	Currency of product. 3 digit ISO-4217 format is preferred.
quantity	integer	The quantity of a product (e.g. 2)
contents	item_list	An array of item type JSON objects. For appropriate structure refer to Item definition in this chapter later.
list	text	The list or collection to which the product belongs (e.g. Search Results)
position	text	The product's position in a list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
creative	text	The creative associated with the promotion (e.g. summer_banner2)
step	integer	A number representing a step in the checkout process. Optional on checkout actions.
coupon	text	The transaction coupon code redeemed with the transaction.
orderNumber	text	Required if the action is purchase.
revenue	float	Specifies the total revenue or grand total associated with the transaction (e.g. 11.99). This value includes shipping, tax costs, or other adjustments to revenue that you want to include as part of your revenue calculations. Note: if revenue is not set, its value will be automatically calculated using the product quantity and price fields of all products in the same hit.
tax	float	The total tax associated with the transaction
shipping	float	The shipping cost associated with the transaction.
shippingAddress	address	This structure represents a shipping address related to a payment. See below the address type for the appropriate structure and syntax.
paymentMethod	text	Payment method of the purchase. E.g. Barion, PayPal, CashOnDelivery, Klarna
option	text	Additional field that can describe option information on the checkout page (e.g. delivery method)
customerValue	float	The value of a user performing this event to the business.
searchString	text	In case of Search event. The string entered by the user for the search.
totalResults	number	Results found in case of a search

User Properties

For the setUserProperties event there are a custom set of properties that may be set when used.

Table 3: setUserProperties properties

Key	Value Type	Description	Required
userId	text	User Id	YES
email	text	Email address. Hashed automatically for privacy purposes.	NO
phone	text	Phone number ina format of IPF ()International Phone Number) eg. +1-541-754-3010. Hashed automatically for privacy purposes.	NO
accountCreatedTime	UNIX timestamp	When the user account was created	NO
country	text	The country in which the user lives. ISO 3166-1 alpha-2 codes are preferred.	NO
county	text	The county in which the user lives	NO
city	text	The city in which the user lives	NO
zipCode	text	The zip code of the user	NO
gender	text	The gender of the user. Possible values: M - Male, F - Female	NO
age	integer	Age of user	NO
currency	text (ISO 4217 format)	The preferred currency of the user. 3 digit currency code required.	NO
language	text (ISO 639-1)	The preferred language of the user. 2 digit country code is required.	NO
interests	text	Lists the interests of the user (e.g., "Arts & Entertainment, Games, Sports")	NO
sessionId	text	Session Id	NO

Item value type

The item_list is a compound value type that is comprised of item type Javascript objects in a standard Javascript array. Each element of the array have to conform to the following property list restrictions.

Table 4: The item value type properties

Property name	Property type	Description	Required
id	text	SKU of product/id of article/the promotion ID/etc.	YES
contentType	text	Possible values: Product/Article/Promotion/Banner/Misc	YES
name	text	Full Name of product/article/promotion etc (e.g. Android T-Shirt or e.g. Summer Sale)	YES
brand	text	Brand part of product/brand described in article	YES
category	text	coat\|winter" or "clothes\|coat\|autumn").	YES
unit	text	The measurement unit of the item.	YES
unitPrice	float	Price of product (the price of one measurement unit of the item).	YES
totalItemPrice	float	The total price of the item.	YES
currency	text (ISO 4217 format)	Currency of product	YES
quantity	integer	The quantity of a product (e.g. 2)	YES
variant	text	The variant of the product (e.g. Black)	NO
description	text	The detailed description of the item.	NO
imageUrl	text	A URL pointing to an image that shows the item.	NO
ean	text	Contains the International Article Number (EAN) when applicable.	NO

Address value type

The shippingAddress property is a compound value type with a specific set of properties. This is essentially a Javascript object with specified keys below. No keys are mandatory in this value type.

Table 5: The address value type properties

Property name	Property type	Description	Required
deliveryMethod	text	The delivery method, if applicable.	No
country	text	The recipient's country code in ISO-3166-1 alpha-2 format.	No
city	text	The complete name of the city of the recipient address.	No
region	text	The region code of the recipient address in ISO-3166-2 format	No
zip	text	The zip code of the recipient address.	No
street	text	The shipping street address with house number and other details.	No
street2	text	The address, continued.	No
fullName	text	The full civil or official name of the recipient.	No
phone	text	The phone number of the recipient.	No

Events related to content browsing

A portion of all events are related to browsing through a Your webshop’s content: viewing pages, promotions, clicking on products and product details, customization of products, etc. These are specifically: contentView, clickProduct, clickProductDetail, customizeProduct, clickPromo. All properties may be used in each event, where You find YES in te corresnponding table the property usage is mandatory. Only 3 properties are overall mandatory, these are: id, contentType and name. Please note that for the contentType property, you are only able to choose from a number of predefined values: Page, Product, Article, Promotion, Banner and Misc. The following table shows the property requirements for these.

Table 6: Properties of events related to content browsing

	Event
Property	contentView	clickProduct	clickProductDetail	customizeProduct	clickPromo
contentType	YES	YES	YES	YES	YES
id	YES	YES	YES	YES	YES
name	YES	YES	YES	YES	YES
unitPrice	YES*	YES	YES	YES
unit	YES*	YES	YES	YES
currency	YES*	YES	YES	YES
quantity	YES*	YES
variant				YES
creative					YES
contents
ean
brand
category
list
position
step
customerValue
	* Required only in case of Product type when using the contentView event.

Purchase related events

These events refer to purchase intentions and effective checkouts and purchases. These events also share a number of common properties.

addToCart/removeFromCart

Both events have the same event set and the required properties are the same as well.

Table 7: addToCart/removeFromCart event properties

Property	Required
contentType	YES
currency	YES
id	YES
name	YES
quantity	YES
totalItemPrice	YES
unit	YES
unitPrice	YES
brand
category
contents
coupon
creative
customerValue
ean
list
position
step
variant

initiateCheckout, addPaymentInfo, initiatePurchase, purchase

These events refer to checkout and payment info change user events. The allowed properties are generally the same with only one exception: the paymentMethod property is only allowed in the addPaymentInfo event, in other events it is unavailable.

Generally two properties are mandatory throughout all events in this particular group: contents and step, referring to the items in the basket and the step in the buying process. After checkout is initiated the revenue and currency also becomes mandatory property.

Table 8: Properties of initiateCheckout, addPaymentInfo, initiatePurchase and purchase events

	event
Property	initiateCheckout	addPaymentInfo	initiatePurchase	purchase
contents	YES	YES	YES	YES
step	YES	YES	YES	YES
paymentMethod	UNAVAILABLE	YES	UNAVAILABLE	UNAVAILABLE
revenue		YES	YES	YES
currency		YES	YES	YES
brand
category
contentType
coupon
creative
customerValue
description
ean
id
imageUrl
list
name
option
orderNumber
position
quantity
shipping
shippingAddress
tax
totalItemPrice
unit
unitPrice
variant

Search event

For product search event tracking one can use the search event. The parameters here are all optional except for one: that is the searchString. The following tables lists all allowed properties for this particular event.

Table 9: Properties of search event

Key	Required
searchString	YES
contentType
id
name
contents
totalResults
customerValue
currency

signUp event

Upon user signup one may fire the signUp event to record signups for theri webshop. All but three properties are optional. Mandatory properties are: id, contentType and name. Other attributes are denoted in the following table.

Table 10: Properties of signUp event

Key	Required
contentType	YES
id	YES
name	YES
contents
customerValue
currency
ean
brand
category
variant
unit
unitPrice
totalItemPrice

@@ Line 564: / Line 564: @@
 All properties may be used in each event, where You find YES in te corresnponding table the property usage is mandatory. Only 3 properties are overall mandatory, these are: '''id, contentType and name'''. Please note that for the contentType property, you are only able to choose from a number of predefined values: Page, Product, Article, Promotion, Banner and Misc. The following table shows the property requirements for these.
-====Table 6: Properties of events related to content browsing====
+'''Table 6: Properties of events related to content browsing'''
 {| class="wikitable"

Barion Pixel API reference: Difference between revisions