Barion Pixel API reference: Difference between revisions
No edit summary |
|||
Line 1: | Line 1: | ||
{{PageTitle|title=Barion Pixel | {{PageTitle|title=Barion Pixel}} | ||
{| style="margin-left:2em;" align="right" | {| style="margin-left:2em;" align="right" | ||
Line 5: | Line 5: | ||
|} | |} | ||
The Barion Pixel is | The Barion Pixel is JavaScript code that allows you to track visitor activity on your website. It works by loading a | ||
JavaScript function which you can use whenever a site visitor takes an action that you want to track (this action is | |||
called an event). | |||
In order to implement the Pixel, you will need: | In order to implement the Pixel, you will need: | ||
* access to your website's code base | * access to your website's HTML code base | ||
* your Pixel | * your Barion Pixel ID that you can access from your Barion Wallet | ||
By default, the Pixel will track pages visited, and the devices your visitors use. In addition, you can use the | |||
Pixel's JavaScript function to track other events that are associated with webshop usage and e-commerce. Without | |||
collecting the consent of the website visitor you must still use the Barion Pixel on your website for fraud management | |||
purposes. (Tracking visitor behavior for the purposes of preventing fraud is considered a legitimate interest of | |||
Barion and the merchant in contract with Barion). If you collect the consent of your visitors (see consent events | |||
below in Minimum requirements) for marketing purposes, you can get lower fees for your Barion Smart Gateway. The | |||
implementation of the base code is considered mandatory for using the Barion Smart Gateway. | |||
= | = Implementing the base code = | ||
== Base code == | |||
To install the Pixel, we highly recommend that you add the following code (referred to as the base code) between the | |||
opening and closing <head> tags on every page of your site. Most developers add it to their website's persistent header, | |||
so that it appears automatically on all loaded pages. | |||
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. Sending the tracking data happens asynchronously in the client's browser so that it does not slow user experience. | |||
'''Figure 1''' | |||
<nowiki> | |||
''' | <script> | ||
<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', 'https://pixel.barion.com/bp.js', 'bp'); | |||
// send page view event | |||
bp('init', 'addBarionPixelId', '[Your Barion Pixel ID goes here]'); | |||
</script> | |||
<noscript> | |||
</ | <img height="1" width="1" style="display:none" src="https://pixel.barion.com/a.gif?__ba_pixel_id=[Your Barion Pixel ID goes here]&ev=contentView&noscript=1"/> | ||
</noscript> | |||
</nowiki> | |||
When run, this code will | When run, this code will make available a JavaScript function which you can then use for tracking. It also automatically | ||
tracks a single PageView conversion by calling the tracking bp() function each time it loads. We recommend that you | |||
leave this function call intact. | |||
== Consent Events == | |||
Consent events determine which data could be used by | Consent events determine which of the sent data could be used by us for marketing purposes. Two consent events can be | ||
used to control user consent. The "grantConsent" event has to be sent when the visitor accepts the cookie policy | |||
that expressly allows Barion to use data for marketing purposes. The "rejectConsent" event should be sent when the | |||
customer rejects the cookie policy that includes Barion Pixel tracking. It should be noted that rejecting Barion | |||
marketing consent does not mean that no data should be sent towards Barion, since Barion has a legitimate interest using | |||
this data for fraud management. All consent events are tracked by calling the Pixel's bp('consent') function as shown | |||
below. | |||
'''Figure 2''' | '''Figure 2''' | ||
<nowiki> | |||
bp('consent', 'grantConsent'); | |||
bp('consent', 'rejectConsent'); | |||
</nowiki> | |||
= | = Implementing Standard and Custom Events = | ||
There are two ways to track conversions with the Pixel: | 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 | * 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 | * 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 | 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 require parameters, which must be | |||
included in the bp function call parameters as an object containing additional information about an event, such as | |||
product IDs, categories, and the number of products purchased. Some events have mandatory properties (see below). In | |||
order to track an event, the code tracking the event needs to be added with its properties into your page JavaScript | |||
either through a <script> tag or sourced JS files. | |||
All standard events are tracked by calling the Pixel's bp('track') function, with the event name, and a JSON object as | |||
its parameters. | |||
'''Figure 3''' | |||
<nowiki> | |||
''' | // contentView event tracking example | ||
var contentViewProperties = { | |||
'id': 'promo01', | |||
'contentType': 'Promotion', | |||
'name': 'Winter tires 20% off', | |||
} | |||
bp('track', 'contentView', contentViewProperties); | |||
</nowiki> | |||
Sometimes | Sometimes you may want to track this event when a specific button is clicked. This can be achieved as in the example | ||
below (note that you may use technologies that require different syntax, like the below example using jQuery). Note that | |||
the Pixel base code needs to be included in the page in order to be able to track events. | |||
'''Figure 4''' | '''Figure 4''' | ||
<nowiki> | |||
// sample product data | |||
var addToCartProperties = { | |||
'id': 'item001', | |||
'contentType': 'Page', | |||
'name': 'first', | |||
'ean': '9501101530003', | |||
'unitPrice': 1000, | |||
'totalItemPrice': 2000, | |||
'unit': 'kg', | |||
'currency': 'huf', | |||
'quantity': 2, | |||
} | |||
// tracking the event | |||
document.getElementById('addtocart_button').addEventListener('click', function() { | |||
bp('track', 'addToCart', addToCartProperties); | |||
}); | |||
</nowiki> | |||
Tracking the same event with jQuery: | |||
<nowiki> | |||
// sample product data | |||
var addToCartProperties = { | |||
'id': 'item001', | |||
'contentType': 'Page', | |||
'name': 'first', | |||
'ean': '9501101530003', | |||
'unitPrice': 1000, | |||
'totalItemPrice': 2000, | |||
'unit': 'kg', | |||
'currency': 'huf', | |||
'quantity': 2, | |||
} | |||
// tracking the event with jQuery | |||
$("#addtocart_button").click(function() { | |||
bp('track', 'addToCart', addToCartProperties); | |||
}); | |||
</nowiki> | |||
== Standard event descriptions == | |||
With these standard events | With these standard events you can describe a lot of ecommerce related user actions in a meaningful way. Each event has | ||
its own set of properties that is needed in order to fully understand and record the users' intentions. | |||
'''Table 1: Event descriptions''' | '''Table 1: Event descriptions''' | ||
Line 181: | Line 234: | ||
|} | |} | ||
== 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. | 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. | ||
Line 194: | Line 247: | ||
eventProperty: 'video', | eventProperty: 'video', | ||
eventLabel: 'Fall Campaign', | eventLabel: 'Fall Campaign', | ||
eventValue: 42 | eventValue: 42 | ||
} | } | ||
bp('track', 'customEvent', customData); | |||
</nowiki> | </nowiki> | ||
Line 210: | Line 263: | ||
} | } | ||
bp('track', 'contentView', contentViewProperties); | |||
</nowiki> | </nowiki> | ||
== 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. | 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. | 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. | 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. | ||
Line 292: | Line 345: | ||
! contents | ! contents | ||
| item_list | | item_list | ||
| An array of item type JSON objects. For appropriate structure refer to Item definition in this chapter later. | | An array of item type JSON objects. For appropriate structure refer to Item definition in this chapter later. | ||
|- | |- | ||
! list | ! list | ||
Line 355: | Line 408: | ||
|} | |} | ||
=== User Properties === | |||
For the '''setUserProperties''' event there are a custom set of properties that may be set when used. | For the '''setUserProperties''' event there are a custom set of properties that may be set when used. | ||
Line 444: | Line 497: | ||
|} | |} | ||
=== Contetnts value type === | |||
The '''contents''' is a compound value type that is comprised of a standard Javascript dictionary encapsulated in a standard JS array. Each element of the array have to conform to the following property list restrictions. | The '''contents''' is a compound value type that is comprised of a standard Javascript dictionary encapsulated in a standard JS array. Each element of the array have to conform to the following property list restrictions. | ||
Line 568: | Line 621: | ||
} | } | ||
bp('track', 'addToCart', addToCartProperties ); | |||
</nowiki> | </nowiki> | ||
=== 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. | 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. | ||
Line 647: | Line 700: | ||
</nowiki> | </nowiki> | ||
== 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'''. | 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. | 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. | ||
Line 692: | Line 745: | ||
| YES | | YES | ||
| YES | | YES | ||
| | | | ||
|- | |- | ||
! unit | ! unit | ||
Line 699: | Line 752: | ||
| YES | | YES | ||
| YES | | YES | ||
| | | | ||
|- | |- | ||
! currency | ! currency | ||
Line 706: | Line 759: | ||
| YES | | YES | ||
| YES | | YES | ||
| | | | ||
|- | |- | ||
! quantity | ! quantity | ||
| YES* | | YES* | ||
| YES | | YES | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! variant | ! variant | ||
| | | | ||
| | | | ||
| | | | ||
| YES | | YES | ||
| | | | ||
|- | |- | ||
! creative | ! creative | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| YES | | YES | ||
|- | |- | ||
! contents | ! contents | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! ean | ! ean | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! brand | ! brand | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! category | ! category | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! list | ! list | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! position | ! position | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! step | ! step | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! customerValue | ! customerValue | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! | ! | ||
|colspan = "5"| * Required only in case of contentType=Product when using the contentView event. | |colspan = "5"| * Required only in case of contentType=Product 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. | 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. | Both events have the same event set and the required properties are the same as well. | ||
Line 829: | Line 882: | ||
|- | |- | ||
! brand | ! brand | ||
| | | | ||
|- | |- | ||
! category | ! category | ||
| | | | ||
|- | |- | ||
! contents | ! contents | ||
| | | | ||
|- | |- | ||
! coupon | ! coupon | ||
| | | | ||
|- | |- | ||
! creative | ! creative | ||
| | | | ||
|- | |- | ||
! customerValue | ! customerValue | ||
| | | | ||
|- | |- | ||
! ean | ! ean | ||
| | | | ||
|- | |- | ||
! list | ! list | ||
| | | | ||
|- | |- | ||
! position | ! position | ||
| | | | ||
|- | |- | ||
! step | ! step | ||
| | | | ||
|- | |- | ||
! variant | ! 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. | 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. | 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. | ||
Line 900: | Line 953: | ||
|- | |- | ||
! revenue | ! revenue | ||
| | | | ||
| YES | | YES | ||
| YES | | YES | ||
Line 906: | Line 959: | ||
|- | |- | ||
! currency | ! currency | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! contentType | ! contentType | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! coupon | ! coupon | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! creative | ! creative | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! customerValue | ! customerValue | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! list | ! list | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! option | ! option | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! orderNumber | ! orderNumber | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! position | ! position | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! shipping | ! shipping | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! shippingAddress | ! shippingAddress | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|- | |- | ||
! tax | ! tax | ||
| | | | ||
| | | | ||
| | | | ||
| | | | ||
|} | |} | ||
=== 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. | 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. | ||
Line 993: | Line 1,046: | ||
|- | |- | ||
! contentType | ! contentType | ||
| | | | ||
|- | |- | ||
! id | ! id | ||
| | | | ||
|- | |- | ||
! name | ! name | ||
| | | | ||
|- | |- | ||
! contents | ! contents | ||
| | | | ||
|- | |- | ||
! totalResults | ! totalResults | ||
| | | | ||
|- | |- | ||
! customerValue | ! customerValue | ||
| | | | ||
|- | |- | ||
! currency | ! 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. | 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. | ||
Line 1,035: | Line 1,088: | ||
|- | |- | ||
! contents | ! contents | ||
| | | | ||
|- | |- | ||
! customerValue | ! customerValue | ||
| | | | ||
|- | |- | ||
! currency | ! currency | ||
| | | | ||
|- | |- | ||
! ean | ! ean | ||
| | | | ||
|- | |- | ||
! brand | ! brand | ||
| | | | ||
|- | |- | ||
! category | ! category | ||
| | | | ||
|- | |- | ||
! variant | ! variant | ||
| | | | ||
|- | |- | ||
! unit | ! unit | ||
| | | | ||
|- | |- | ||
! unitPrice | ! unitPrice | ||
| | | | ||
|- | |- | ||
! totalItemPrice | ! totalItemPrice | ||
| | | | ||
|} | |} | ||
=== error event === | |||
Tracking error is possible by error event. It has two mandatory properties. It is denoted in the following table. Example in Figure 9. | Tracking error is possible by error event. It has two mandatory properties. It is denoted in the following table. Example in Figure 9. | ||
Line 1,092: | Line 1,145: | ||
} | } | ||
bp('track', 'error', errorData); | |||
</nowiki> | </nowiki> |
Revision as of 15:31, 30 April 2019
Barion Pixel
The Barion Pixel is JavaScript code that allows you to track visitor activity on your website. It works by loading a JavaScript function which you can use whenever a site visitor takes an action that you want to track (this action is called an event).
In order to implement the Pixel, you will need:
- access to your website's HTML code base
- your Barion Pixel ID that you can access from your Barion Wallet
By default, the Pixel will track pages visited, and the devices your visitors use. In addition, you can use the Pixel's JavaScript function to track other events that are associated with webshop usage and e-commerce. Without collecting the consent of the website visitor you must still use the Barion Pixel on your website for fraud management purposes. (Tracking visitor behavior for the purposes of preventing fraud is considered a legitimate interest of Barion and the merchant in contract with Barion). If you collect the consent of your visitors (see consent events below in Minimum requirements) for marketing purposes, you can get lower fees for your Barion Smart Gateway. The implementation of the base code is considered mandatory for using the Barion Smart Gateway.
Implementing the base code
Base code
To install the Pixel, we highly recommend that you add the following code (referred to as the base code) between the opening and closing <head> tags on every page of your site. Most developers add it to their website's persistent header, so that it appears automatically on all loaded pages.
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. Sending the tracking data happens asynchronously in the client's browser so that it does not slow user experience.
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', 'https://pixel.barion.com/bp.js', 'bp'); // send page view event bp('init', 'addBarionPixelId', '[Your Barion Pixel ID goes here]'); </script> <noscript> <img height="1" width="1" style="display:none" src="https://pixel.barion.com/a.gif?__ba_pixel_id=[Your Barion Pixel ID goes here]&ev=contentView&noscript=1"/> </noscript>
When run, this code will make available a JavaScript function which you can then use for tracking. It also automatically tracks a single PageView conversion by calling the tracking bp() function each time it loads. We recommend that you leave this function call intact.
Consent Events
Consent events determine which of the sent data could be used by us for marketing purposes. Two consent events can be used to control user consent. The "grantConsent" event has to be sent when the visitor accepts the cookie policy that expressly allows Barion to use data for marketing purposes. The "rejectConsent" event should be sent when the customer rejects the cookie policy that includes Barion Pixel tracking. It should be noted that rejecting Barion marketing consent does not mean that no data should be sent towards Barion, since Barion has a legitimate interest using this data for fraud management. All consent events are tracked by calling the Pixel's bp('consent') function as shown below.
Figure 2
bp('consent', 'grantConsent'); bp('consent', 'rejectConsent');
Implementing Standard and Custom Events
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 require parameters, which must be included in the bp function call parameters as an object containing additional information about an event, such as product IDs, categories, and the number of products purchased. Some events have mandatory properties (see below). In order to track an event, the code tracking the event needs to be added with its properties into your page JavaScript either through a <script> tag or sourced JS files.
All standard events are tracked by calling the Pixel's bp('track') function, with the event name, and a JSON object as its parameters.
Figure 3
// contentView event tracking example var contentViewProperties = { 'id': 'promo01', 'contentType': 'Promotion', 'name': 'Winter tires 20% off', } bp('track', 'contentView', contentViewProperties);
Sometimes you may want to track this event when a specific button is clicked. This can be achieved as in the example below (note that you may use technologies that require different syntax, like the below example using jQuery). Note that the Pixel base code needs to be included in the page in order to be able to track events.
Figure 4
// sample product data var addToCartProperties = { 'id': 'item001', 'contentType': 'Page', 'name': 'first', 'ean': '9501101530003', 'unitPrice': 1000, 'totalItemPrice': 2000, 'unit': 'kg', 'currency': 'huf', 'quantity': 2, } // tracking the event document.getElementById('addtocart_button').addEventListener('click', function() { bp('track', 'addToCart', addToCartProperties); });
Tracking the same event with jQuery:
// sample product data var addToCartProperties = { 'id': 'item001', 'contentType': 'Page', 'name': 'first', 'ean': '9501101530003', 'unitPrice': 1000, 'totalItemPrice': 2000, 'unit': 'kg', 'currency': 'huf', 'quantity': 2, } // tracking the event with jQuery $("#addtocart_button").click(function() { bp('track', 'addToCart', addToCartProperties); });
Standard event descriptions
With these standard events you can describe a lot of ecommerce related user actions in a meaningful way. Each event has its own set of properties that is needed in order to fully understand and record the users' intentions.
Table 1: Event descriptions
Event name | Description | Typical use cases |
---|---|---|
setUserProperties | With this event One can add user related information. | Registration, login, account details in chechkout step, sign up for newsletter, contact request |
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. | E.g. product details in product page. |
clickProduct | A click on a product in any list (search, recommendation box, etc). Usually fired at user click | Product means that webshop provides e.g. physical item, ticket, food, service |
clickProductDetail | A click of product details. (e.g. more info link). Usually fired when user clicks. | Button to show more info about product, link to producer's webpage or user manual, review about product |
customizeProduct | When a person customizes a product. (color, size, etc). Typically fired at user click. | E.g. radio button about color on product page |
clickPromo | A click on an internal promotion. Fired at mouse click. | Promotion has general meaning. Promo means to click on element in category selection page (e.g. Samsung TVs, Outdoor bulbs, Horror movies, Festivals 2019, concerts), recommendation product box, top product box, promotion on basket page/in chehckout/ on Home page (slider) too. Category means group of product that based on their characteristic. |
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. | The step property has to be started from 0. |
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. | It is typically called thank you page where tha customer get a feedback about his/her purchase. If the feedback is unsuccessful the step property has to be -1. |
search | When a search is entered into a search field upon sending the form, this event may be fired. | Search input box, ajax product filter by different attributes (e.g. price, size, color, brand, etc.) |
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. | SignUp event has general meaning. It could be means registration, newsletter, contact request, etc. Usually signUp event pulls a setUserProperties event but it is not necessary. |
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 5: Custom event tracking
// sample customData var customData = { eventCategory: 'Video', eventAction: 'play', eventProperty: 'video', eventLabel: 'Fall Campaign', eventValue: 42 } bp('track', 'customEvent', customData);
Figure 6: Custom event tracking
var contentViewProperties = { 'id': 'My blog page', 'contentType': 'Page', 'name': 'Very cool product', '_mycustomparameter': 42 } bp('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 | Array of categories of product/article/etc. If category is in tree structure, they must be separated with pipe e.g. "clothes|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. Possible values: HomePage\SearchPage\ProductPage\Recommendation\ComparisonPage\BasketPage\Checkout\Misc |
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 represents a step in the checkout process. Optional on checkout actions. If the feedback is unsuccessful on Thank You Page the step has to be -1. The step has to be started from 0. (initiateCheckout event) |
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 |
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 |
step | integer | A number represents a step in the checkout process. Optional on checkout actions. | NO |
sessionId | text | Session Id | NO |
Contetnts value type
The contents is a compound value type that is comprised of a standard Javascript dictionary encapsulated in a standard JS array. Each element of the array have to conform to the following property list restrictions.
Table 4: The contents 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 |
Figure 7
var addToCartProperties = { 'id': 'testAddToCart', 'contentType': 'testType', 'name': 'testName', 'contents': [{ 'id': 'testId', 'contentType': 'testAnimal', 'name': 'testName', 'brand': 'testDead', 'category': 'testCategory', 'unit': 'testUnit', 'unitPrice': 10000.0, 'totalItemPrice': 100000.0, 'currency': 'HUF', 'quantity': 10, 'ean': '234eqwfq24241324r345', 'variant': 'testVariant', 'description': 'testDescription', 'imageUrl': 'http://example.org/test.jpg', }], 'ean': 'a124jiojrega231', 'brand': 'testBrand', 'category': 'testCategory', 'variant': 'testVariant', 'list': 'testList', 'position': 'testPosition', 'creative': 'testCreative', 'unitPrice': 10000.0, 'totalItemPrice': 100000.0, 'unit': 'db', 'currency': 'HUF', 'quantity': 10, 'step': 6, 'customerValue': 15.00, 'coupon': 'testCoupon' } bp('track', 'addToCart', addToCartProperties );
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 |
Figure 8
'shippingAddress': { 'deliveryMethod': 'ship', 'country': 'Africa', 'city': 'Egypt', 'region': 'idn', 'zip': '98772', 'street': 'Cleopatra street 24', 'street2': 'Faro street 49', 'fullName': 'Sir Lancelot', 'phone': '+367187242' }
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 contentType=Product when using the contentView event. |
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 | ||||
contentType | ||||
coupon | ||||
creative | ||||
customerValue | ||||
list | ||||
option | ||||
orderNumber | ||||
position | ||||
shipping | ||||
shippingAddress | ||||
tax |
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 |
error event
Tracking error is possible by error event. It has two mandatory properties. It is denoted in the following table. Example in Figure 9.
Table 11: Properties of error event
Key | Required |
---|---|
code | YES |
description | YES |
Figure 9
var errorData = { 'description': 'testError', 'code': 485, } bp('track', 'error', errorData);