Difference between revisions of "Barion Pixel"

From Barion Documentation
Jump to navigation Jump to search
(List properties by event)
Line 17: Line 17:
 
collecting the consent of the website visitor you must still use the Barion Pixel on your website for fraud management
 
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
 
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
+
Barion and the merchant in contract with Barion). The implementation of the base code is considered mandatory for using
below in Minimum requirements) for marketing purposes, you can get lower fees for your Barion Smart Gateway. The
+
the Barion Smart Gateway.
implementation of the base code is considered mandatory for using the Barion Smart Gateway.
+
 
  
 
= Implementing the base code =
 
= Implementing the base code =
  
== Base code ==
+
Implementing the base code is not only required for you to be considered for special offers relating to the Barion
To install the Pixel, we highly recommend that you add the following code (referred to as the base code) between the
+
Pixel, but also for using the Barion Smart Gateway at all. This is based on the fact that both Barion and you as the
opening and closing <head> tags on every page of your site. Most developers add it to their website's persistent header,
+
website owner have a legitimate interest in fraud management, and the data provided by the Barion Pixel greatly helps
so that it appears automatically on all loaded pages.
+
these efforts. This, as a legitimate interest case, is fully compliant with the GDPR, and must be implemented
 +
independently of any consent management software that your site may use.
 +
 
 +
== Init ==
 +
 
 +
* User intent: View pages on your site
 +
* To be implemented at: Every page load, in the document head tag
 +
* Why do we need this: This provides very basic information on user sessions, and can be implemented very easily
 +
 
 +
To use the Pixel, you need to 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. Be sure to insert your unique Barion Pixel ID at both locations in the provided code
 +
example.
  
 
Placing the code within your <head> tags reduces the chances of browsers or third-party code blocking the Pixel's
 
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
 
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.
+
page. Sending the data happens asynchronously in the client's browser so that it does not affect user experience.
  
'''Figure 1'''
+
'''Implementation of the base code'''
  
 
     <nowiki>
 
     <nowiki>
 
 
         <script>
 
         <script>
 
 
             (function(i,s,o,g,r,a,m){i['BarionAnalyticsObject']=r;i[r]=i[r]||function(){
 
             (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),
 
             (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
Line 45: Line 55:
 
             // send page view event
 
             // send page view event
 
             bp('init', 'addBarionPixelId', '</nowiki><span style="color:red">[YOUR BARION PIXEL ID GOES HERE]</span><nowiki>');
 
             bp('init', 'addBarionPixelId', '</nowiki><span style="color:red">[YOUR BARION PIXEL ID GOES HERE]</span><nowiki>');
 
 
         </script>
 
         </script>
  
 
         <noscript>
 
         <noscript>
 
 
             <img height="1" width="1" style="display:none" src="https://pixel.barion.com/a.gif?__ba_pixel_id=</nowiki><span style="color:red">[YOUR BARION PIXEL ID GOES HERE]</span><nowiki>&ev=contentView&noscript=1"/>
 
             <img height="1" width="1" style="display:none" src="https://pixel.barion.com/a.gif?__ba_pixel_id=</nowiki><span style="color:red">[YOUR BARION PIXEL ID GOES HERE]</span><nowiki>&ev=contentView&noscript=1"/>
 
 
         </noscript>
 
         </noscript>
 
 
     </nowiki>
 
     </nowiki>
  
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 ==
+
== Heartbeat ==
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'''
+
* User intent: Browse your site
 +
* To be implemented at: No further implementation needed beyond the init event
 +
* Why do we need this: This provides information on time spent on your various pages
  
    <nowiki>
+
Heartbeat events are sent each minute from each page that the init event is implemented at, as long as the user does not
 +
navigate away from the page or the session is not considered timed out. It can provide information about time spent
 +
viewing each site by users.
  
        bp('consent', 'grantConsent');
 
        bp('consent', 'rejectConsent');
 
  
    </nowiki>
 
  
= Implementing Standard and Custom Events =
+
= Minimal implementation =
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 ==
+
To be considered for the special contract terms in connection with the implementation of the Barion Pixel's full
Standard events are predefined visitor actions that correspond to common conversion-related activities, such as
+
marketing capabilities, you have to implement the following events on your site. All events should be implemented in
searching for a product, viewing a product, or purchasing a product. Standard events require parameters, which must be
+
every location applicable, further detailed below. Events may require parameters, which must be included in the bp
included in the bp function call parameters as an object containing additional information about an event, such as
+
function call as a JS object. This contains additional information about an event, for example product IDs, categories,
product IDs, categories, and the number of products purchased. Some events have mandatory properties (see below). In
+
and the number of products purchased.
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'''
+
== Consent (grantConsent, rejectConsent) ==
  
    <nowiki>
+
* User intent: Give or reject Barion Pixel consent
 +
* To be implemented at: Inside your own consent management software
 +
* Why do we need this: Participation of webshop clients is entirely consent based complying with the GDPR
  
    // contentView event tracking example
+
Consent events determine which of the sent data can be used by us for marketing purposes. Two consent events can be
    var contentViewProperties = {
+
used to control user consent. The "grantConsent" event has to be sent when the visitor accepts the cookie policy
        'id': 'promo01',
+
that expressly allows Barion to use data for marketing purposes. Sending this event must be handled by your own consent
        'contentType': 'Promotion',
+
management implementation that you are responsible for as outlined in our terms. The "rejectConsent" event should be
        'name': 'Winter tires 20% off',
+
sent when the customer rejects the cookie policy that includes Barion Pixel functionality. It should be noted that
    }
+
rejecting Barion marketing consent does not mean that no data should be sent towards Barion, as Barion has a legitimate
 
+
interest using this data for fraud management. Rejecting Barion consent however means that the data from that session
    bp('track', 'contentView', contentViewProperties);
+
will not be used for marketing purposes at all, despite receiving it. All consent events are sent by calling the Pixel's
 +
consent function as shown below.
  
    </nowiki>
+
'''Consent event implementation example'''
 
 
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'''
 
  
 
     <nowiki>
 
     <nowiki>
 
+
         bp('consent', 'grantConsent');
         // sample product data
+
         bp('consent', 'rejectConsent');
        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>
 
     </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
+
== Content View (contentView) ==
        $("#addtocart_button").click(function() {
 
            bp('track', 'addToCart', addToCartProperties);
 
        });
 
  
    </nowiki>
+
* Firing event: ''Page load'' of item pages minimally, preferably on all pages that refers to a single item, offer or promotion
 +
* User intent: View the page that shows a single offer described exclusively
 +
* Why do we need this: Offer descriptions help us know more about your offers
  
== Standard event descriptions ==
+
This event should be fired when one of your users enters a page that refers to one of your items that can be bought,
 +
and describes it in general terms, with an offer to buy. This can be something like an offer page on an e-commerce
 +
website or a product page on a retail site. It is important to not confuse this with a full product detail page where
 +
the product itself is described in greater detail, but there is no information on price, shipping and other details that
 +
are relevant to you offer, like in the case of a product manual.
  
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'''
+
''' Content view event properties '''
  
 
{| class="wikitable"
 
{| class="wikitable"
! Event name
+
! name
! Description
+
! required
! Typical use cases
+
! type
 +
! description
 
|-
 
|-
! [[#User_Properties|setUserProperties]]
+
! contentType
| With this event One can add user related information.
+
| YES
| Registration, login, account details in chechkout step, sign up for newsletter, contact request
+
| text
 +
| If this is a product page as per minimal requirements, this value should be "Product". Otherwise select a value that best fits from these: Page/Product/Article/Promotion/Banner/Misc.
 
|-
 
|-
! [[#Events_related_to_content_browsing|contentView]]
+
! currency
| 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.
+
| YES (in case of "Product")
| E.g. product details in product page.
+
| text (ISO 4217)
 +
| The currency that the product price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
 
|-
 
|-
! [[#Events_related_to_content_browsing|clickProduct]]
+
! id
| A click on a product in any list (search, recommendation box, etc). Usually fired at user click
+
| YES
| Product means that webshop provides e.g. physical item, ticket, food, service
+
| text
 +
| An unique ID that you have for the offer, this can be your ID for the product, an SKU or a promotion ID.
 
|-
 
|-
! [[#Events_related_to_content_browsing|clickProductDetail]]
+
! name
| A click of product details. (e.g. more info link). Usually fired when user clicks.
+
| YES
| Button to show more info about product, link to producer's webpage or user manual, review about product
+
| text
 +
| The full name that you have for the offer, for example a product name (eg. Red Bull 24pcs carton).
 
|-
 
|-
! [[#Events_related_to_content_browsing|customizeProduct]]
+
! quantity
| When a person customizes a product. (color, size, etc). Typically fired at user click.
+
| YES (in case of "Product")
| E.g. radio button about color on product page
+
| float
 +
| The quantity of the product offered as initially given on the page.
 
|-
 
|-
! [[#Events_related_to_content_browsing|clickPromo]]
+
! unit
| A click on an internal promotion. Fired at mouse click.
+
| YES (in case of "Product")
| 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.
+
| text
 +
| The unit that your offer is measured in (eg. pieces, kg, m).
 
|-
 
|-
! [[#addToCart.2FremoveFromCart|addToCart]]
+
! unitPrice
| 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.
+
| YES (in case of "Product")
|
+
| float
 +
| The price of one measurement of your offer in the given currency.
 
|-
 
|-
! [[#addToCart.2FremoveFromCart|removeFromCart]]
+
! brand
| 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.
+
| NO
|
+
| text
 +
| The brand of the offer.
 
|-
 
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|initiateCheckout]]
+
! category
| This event may be fired when a the user checks out the cart, clicks on the checkout button.
+
| NO
| The step property has to be started from 0.
+
| text
 +
| | The subcategory branch (preferred, eg. 'clothes|shoes|winter', separate levels with '|') or single category (eg. 'winter shoes' or 'summer shoes') of the offer.
 
|-
 
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|addPaymentInfo]]
+
! contents
| When payment information is added in the checkout flow, this event may be fired upon user click.
+
| NO
|
+
| array
 +
| An array of JS objects for detailing multiple items of the offer. For more details see the table below.
 
|-
 
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|initiatePurchase]]
+
! creative
| A person clicks on a purchase button (and possibly enters the Thank You Page).
+
| NO
|
+
| text
 +
| The name or description of the promotion, for example a promotion picture filename or slogan.
 
|-
 
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|purchase]]
+
! customerValue
| 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.
+
| NO
| 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.
+
| float
 +
| A metric that you define that measures the value of the action performed to your business.
 
|-
 
|-
! [[#Search_event|search]]
+
! ean
| When a search is entered into a search field upon sending the form, this event may be fired.
+
| NO
| Search input box, ajax product filter by different attributes (e.g. price, size, color, brand, etc.)
+
| text
 +
| Contains the International Article Number (EAN) of the offer if available.
 
|-
 
|-
! [[#signUp_event|signUp]]
+
! list
| 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.
+
| NO
| 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.
+
| text
 +
| THe function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
 
|-
 
|-
! [[#error_event|error]]
+
! position
| If one want to track errors this event may be used for that.
+
| NO
|
+
| text
 +
| The product's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
 +
|-
 +
! step
 +
| NO
 +
| integer
 +
| If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 0 as the checkout initiation.
 +
|-
 +
! variant
 +
| NO
 +
| text
 +
| THe variant of the offer from the list of possible identical items (eg. the color of a phone or the time and venue of a concert or movie)
 
|}
 
|}
  
== 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.
+
'''Content view event implementation example'''
  
'''Figure 5: Custom event tracking'''
+
    <nowiki>
<nowiki>
 
  
// sample customData
+
        // example properties for a product page
var customData = {
+
        var contentViewProperties = {
    eventCategory: 'Video',
+
            'contentType': 'Product',
    eventAction: 'play',
+
            'currency': 'HUF',
    eventProperty: 'video',
+
            'id': 'item_42',
    eventLabel: 'Fall Campaign',
+
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
    eventValue: 42
+
            'quantity': '10',
}
+
            'unit': 'pcs.',
 +
            'unitPrice': 4990.0,
 +
            'brand': 'Gollancz',
 +
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
            'contents': undefined,
 +
            'creative': undefined,
 +
            'customerValue': '150',
 +
            'ean': 9780575115347,
 +
            'list': 'ProductPage',
 +
            'position': undefined,
 +
            'step': undefined,
 +
            'variant': 'hardcover'
 +
        }
  
bp('track', 'customEvent', customData);
+
        // example properties on a home page for a promotion of a product
</nowiki>
+
        var contentViewProperties = {
 +
            'contentType': 'Promotion',
 +
            'currency': 'HUF',
 +
            'id': 'item_42',
 +
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
            'quantity': '10',
 +
            'unit': 'pcs.',
 +
            'unitPrice': 4990.0,
 +
            'brand': 'Gollancz',
 +
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
            'contents': undefined,
 +
            'creative': 'book_promo_02',
 +
            'customerValue': '150',
 +
            'ean': 9780575115347,
 +
            'list': 'HomePage',
 +
            'position': 2,
 +
            'step': undefined,
 +
            'variant': 'hardcover'
 +
        }
  
'''Figure 6: Custom event tracking'''
+
        // example properties on a checkout page for a promotion of a product
 +
        var contentViewProperties = {
 +
            'contentType': 'Promotion',
 +
            'currency': 'HUF',
 +
            'id': 'item_42',
 +
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
            'quantity': '10',
 +
            'unit': 'pcs.',
 +
            'unitPrice': 4990.0,
 +
            'brand': 'Gollancz',
 +
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
            'contents': undefined,
 +
            'creative': 'also_bought_05',
 +
            'customerValue': '150',
 +
            'ean': 9780575115347,
 +
            'list': 'Checkout',
 +
            'position': 5,
 +
            'step': 2,
 +
            'variant': 'hardcover'
 +
        }
  
<nowiki>
+
         // Use one of these to add the event listener to the button click (use only one):
var contentViewProperties = {
 
         'id': 'My blog page',
 
        'contentType': 'Page',
 
        'name': 'Very cool product',
 
        '_mycustomparameter': 42
 
    }
 
  
    bp('track', 'contentView', contentViewProperties);
+
        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
</nowiki>
+
        window.addEventListener('onload', function() {
 +
            bp('track', 'contentView', contentViewProperties);
 +
        });
  
 +
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
 +
        $("window").load(function() {
 +
            bp('track', 'contentView', contentViewProperties);
 +
        });
  
 +
    </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.
 
 
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 ===
+
== Add to Cart (addToCart) ==
  
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.
+
* Firing event: ''Button click'' that results in a product to be selected for purchase
 +
* User intent: Select product for purchase
 +
* Why do we need this: Users demonstrate strong interest in your items by selecting them for purchase
  
 +
The add to cart event is, as its name suggests, connected to a user "adding a product to their cart". Usually this means
 +
that a user decide to purchase a product or service, and has added this item to their cart. Even if your website does
 +
not use carts in the literal sense, there is a point in a user session where the given user decides that they intend to
 +
purchase the product. This exact intent is what we want to capture here, so the button click which best matches the
 +
point of this intent, such as one labeled 'Buy' or 'Reserve' should be the one to attach this event to.
  
'''Table 2: Standard properties'''
 
  
 +
'''Add to cart event properties'''
 
{| class="wikitable"
 
{| class="wikitable"
 
! name
 
! name
 +
! required
 
! type
 
! type
 
! description
 
! description
|-
 
! id
 
| text
 
| SKU of product/id of article/the promotion ID/etc.
 
 
|-
 
|-
 
! contentType
 
! contentType
 +
| YES
 
| text
 
| text
| The content type of the page visited. Possible values: Page/Product/Article/Promotion/Banner/Misc. Values here are enforced/validated.
+
| Usually, this value should be "Product".
 
|-
 
|-
! name
+
! currency
| text
+
| YES
| Full name of product/article/promotion etc (e.g. Android T-Shirt or e.g. Summer Sale)
+
| text (ISO 4217)
 +
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
 
|-
 
|-
! ean
+
! id
 +
| YES
 
| text
 
| text
| Contains the International Article Number (EAN) when applicable.
+
| An unique ID that you have for the item, this can be your ID for the product, an SKU or a promotion ID.
 
|-
 
|-
! brand
+
! name
 +
| YES
 
| text
 
| text
| Brand part of product/brand described in name
+
| The full name that you have for the added item, for example a product name (eg. Red Bull 24pcs carton).
 
|-
 
|-
! category
+
! quantity
| text
+
| YES
| |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".
+
| float
 +
| The quantity of the item added to the cart.
 
|-
 
|-
! variant
+
! totalItemPrice
| text
+
| YES
| The variant of the product (e.g. Black)
+
| float
|-
+
| The total price of the added items in the given currency.
! 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
 
! unit
 +
| YES
 
| text
 
| text
| The measurement unit of the item. (e.g. pcs, litre)
+
| The unit that your item is measured in (eg. pieces, kg, hours).
 
|-
 
|-
 
! unitPrice
 
! unitPrice
 +
| YES
 
| float
 
| float
| Price of product (the price of one measurement unit of the item).
+
| The price of one measurement of your item in the given currency.
 
|-
 
|-
! totalItemPrice
+
! brand
| float
+
| NO
| 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
 
| text
| The list or collection to which the product belongs. Possible values: HomePage\SearchPage\ProductPage\Recommendation\ComparisonPage\BasketPage\Checkout\Misc
+
| The brand of the item.
 
|-
 
|-
! position
+
! category
 +
| NO
 
| text
 
| text
| The product's position in a list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
+
| | The subcategory branch (preferred, eg. 'clothes|shoes|winter', separate levels with '|') or single category (eg. 'winter shoes' or 'summer shoes') of the item.
|-
 
! 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
 
! coupon
 +
| NO
 
| text
 
| text
| The transaction coupon code redeemed with the transaction.
+
| The coupon code that was used when the item was added to cart.
 
|-
 
|-
! orderNumber
+
! contents
| text
+
| NO
| Required if the action is purchase.
+
| array
 +
| An array of JS objects for detailing multiple items of the item. For more details see the table below.
 
|-
 
|-
! revenue
+
! creative
| float
+
| NO
| 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
 
| text
| Additional field that can describe option information on the checkout page (e.g. delivery method)
+
| The name or description of the promotion for the item, for example a promotion picture filename or slogan of the promotion that adds the items to the cart automatically.
 
|-
 
|-
 
! customerValue
 
! customerValue
 +
| NO
 
| float
 
| float
| The value of a user performing this event to the business.
+
| A metric that you define that measures the value of the action performed to your business.
 
|-
 
|-
! searchString
+
! ean
| 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'''
 
 
 
{| class="wikitable"
 
! Key
 
! Value Type
 
! Description
 
! Required
 
|-
 
! userId
 
| text
 
| User Id
 
| YES
 
|-
 
! email
 
| text
 
| Email address. '''Hashed automatically for privacy purposes.'''
 
 
| NO
 
| NO
|-
 
! phone
 
 
| text
 
| text
| Phone number ina format of IPF ()International Phone Number) eg. +1-541-754-3010. '''Hashed automatically for privacy purposes.'''
+
| Contains the International Article Number (EAN) of the offer if available.
| NO
 
 
|-
 
|-
! accountCreatedTime
+
! list
| UNIX timestamp
 
| When the user account was created
 
 
| NO
 
| NO
|-
 
! country
 
 
| text
 
| text
| The country in which the user lives. ISO 3166-1 alpha-2 codes are preferred.
+
| THe function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
| NO
 
 
|-
 
|-
! county
+
! position
| text
 
| The county in which the user lives
 
 
| NO
 
| NO
|-
 
! city
 
 
| text
 
| text
| The city in which the user lives
+
| The item's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
| NO
 
 
|-
 
|-
! zipCode
+
! step
| text
 
| The zip code of the user
 
 
| NO
 
| NO
|-
 
! gender
 
| text
 
| The gender of the user. Possible values: M - Male, F - Female
 
| NO
 
|-
 
! age
 
 
| integer
 
| integer
| Age of user
+
| If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 0 as the checkout initiation.
| NO
 
 
|-
 
|-
! currency
+
! variant
| 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
 
| 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
 
| text
| Session Id
+
| THe variant of the offer from the list of possible identical items (eg. the color of a phone or the time and venue of a concert or movie)
| 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.
 
  
 +
'''Add to cart event implementation example'''
 +
 +
    <nowiki>
 +
 +
        // sample product data
 +
        var addToCartProperties = {
 +
            'contentType': 'Product',
 +
            'currency': 'HUF',
 +
            'id': 'item_42',
 +
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
            'quantity': '10',
 +
            'totalItemPrice': 49900.0,
 +
            'unit': 'pcs.',
 +
            'unitPrice': 4990.0,
 +
            'brand': 'Gollancz',
 +
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
            'contents': undefined,
 +
            'coupon': '43763436874'
 +
            'creative': undefined,
 +
            'customerValue': '150',
 +
            'ean': 9780575115347,
 +
            'list': 'ProductPage',
 +
            'position': undefined,
 +
            'step': undefined,
 +
            'variant': 'hardcover'
 +
        }
  
'''Table 4: The contents type properties'''
+
        // Use one of these to add the event listener to the button click (use only one):
  
 +
        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
 +
        document.getElementById('addtocart_button').addEventListener('click', function() {
 +
            bp('track', 'addToCart', addToCartProperties);
 +
        });
 +
 +
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
 +
        $("#addtocart_button").click(function() {
 +
            bp('track', 'addToCart', addToCartProperties);
 +
        });
 +
 +
    </nowiki>
 +
 +
 +
== Initiate Checkout (initiateCheckout) ==
 +
 +
* Firing event: ''Button click'' that starts the checkout process
 +
* User intent: Purchase the items in the cart
 +
* Why do we need this: Users usually are put off by adverts of an item they already purchased, but can be receptive to related products
 +
 +
Usually on a webshop, there is a checkout process that starts with clicking a button with items in your cart. This
 +
button click is the one that this event should be attached to. After this click, typically the user has to provide other
 +
data, such as a shipping address and method, and confirm the purchase (which should fire the initiate purchase event).
 +
 +
 +
'''Initiate checkout event properties'''
 
{| class="wikitable"
 
{| class="wikitable"
! Property name
+
! name
! Property type
+
! required
! Description
+
! type
! Required
+
! description
 
|-
 
|-
! id
+
! contents
| text
 
| SKU of product/id of article/the promotion ID/etc.
 
 
| YES
 
| YES
 +
| array
 +
| An array of JS objects for detailing the actual items contained in the cart, meaning the shipping and coupons should be excluded. For the detailed format see the table below.
 
|-
 
|-
! contentType
+
! currency
| text
 
| Possible values: Product/Article/Promotion/Banner/Misc
 
 
| YES
 
| YES
 +
| text (ISO 4217)
 +
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
 
|-
 
|-
! name
+
! revenue
| text
 
| Full Name of product/article/promotion etc (e.g. Android T-Shirt or e.g. Summer Sale)
 
 
| YES
 
| YES
 +
| float
 +
| The total revenue associated with the transaction in the given currency. This should include all costs the customer pays like shipping or tax.
 
|-
 
|-
! brand
+
! step
| text
 
| Brand part of product/brand described in article
 
 
| YES
 
| YES
 +
| integer
 +
| In most cases, since this is the first checkout step, this should be 0.
 
|-
 
|-
! category
+
! contentType
 +
| NO
 
| text
 
| 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").
+
| Usually this value should be "Product".
| YES
 
 
|-
 
|-
! unit
+
! coupon
 +
| NO
 
| text
 
| text
| The measurement unit of the item.
+
| The coupon code that is being used.
| YES
 
 
|-
 
|-
! unitPrice
+
! creative
| float
+
| NO
| Price of product (the price of one measurement unit of the item).
+
| text
| YES
+
| The name or description of the promotion for the cart, for example a promotion picture filename or slogan of the promotion that starts the checkout automatically.
 
|-
 
|-
! totalItemPrice
+
! customerValue
 +
| NO
 
| float
 
| float
| The total price of the item.
+
| A metric that you define that measures the value of the action performed to your business.
| YES
 
 
|-
 
|-
! currency
+
! list
| text (ISO 4217 format)
+
| NO
| Currency of product
+
| text
| YES
+
| In most cases this should be 'Checkout'.
 
|-
 
|-
! quantity
+
! option
| integer
+
| NO
| The quantity of a product (e.g. 2)
+
| text
| YES
+
| Additional information about the purchase.
 
|-
 
|-
! variant
+
! orderNumber
 +
| NO
 
| text
 
| text
| The variant of the product (e.g. Black)
+
| The unique ID of the purchase.
 +
|-
 +
! position
 
| NO
 
| NO
 +
| text
 +
| The item's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
 
|-
 
|-
! description
+
! shipping
| text
 
| The detailed description of the item.
 
 
| NO
 
| NO
 +
| float
 +
| The price of shipping associated with the purchase in the given currency.
 
|-
 
|-
! imageUrl
+
! shippingAddress
| text
 
| A URL pointing to an image that shows the item.
 
 
| NO
 
| NO
 +
| object
 +
| The shipping address given in the format detailed below.
 
|-
 
|-
! ean
+
! tax
| text
 
| Contains the International Article Number (EAN) when applicable.
 
 
| NO
 
| NO
 +
| float
 +
| The tax associated with the purchase in the given currency.
 
|}
 
|}
  
'''Figure 7'''
 
  
<nowiki>
 
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 );
+
'''Initiate checkout event implementation example'''
</nowiki>
 
  
=== Address value type ===
+
    <nowiki>
  
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.
+
        // sample product data
 +
        var initiateCheckoutProperties = {
 +
            'contents': [{
 +
                'contentType': 'Product',
 +
                'currency': 'HUF',
 +
                'id': 'item_42',
 +
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
                'quantity': 3,
 +
                'totalItemPrice': 7500.0,
 +
                'unit': 'pcs',
 +
                'unitPrice': 2500.0,
 +
                'brand': 'Gollancz',
 +
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
 +
                'ean': 9780575115347,
 +
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
 +
                'variant': 'hardcover'
 +
                },
 +
                {
 +
                'contentType': 'Product',
 +
                'currency': 'USD',
 +
                'id': 'item_42en',
 +
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
                'quantity': 3,
 +
                'totalItemPrice': 25.935,
 +
                'unit': 'pcs',
 +
                'unitPrice': 8.645,
 +
                'brand': 'Gollancz',
 +
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
 +
                'ean': 9780575115347,
 +
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
 +
                'variant': 'hardcover'
 +
                },
 +
            ]
 +
            'currency': 'HUF',
 +
            'revenue': 17500.0,
 +
            'step': 0,
 +
            'contentType': 'Product',
 +
            'coupon': '43763436874'
 +
            'creative': 'preselected_cart_01',
 +
            'customerValue': '150',
 +
            'list': 'Checkout',
 +
            'option': 'To postal office, no street address',
 +
            'orderNumber': 852,
 +
            'position': 1,
 +
            'shipping': 2500.0,
 +
            'shippingAddress': {
 +
                'city': 'Budapest',
 +
                'country': 'HU',
 +
                'deliveryMethod': 'DHL',
 +
                'fullName': 'John Doe',
 +
                'phone': '+36 1 1111 111',
 +
                'region': 'HU-BU',
 +
                'street': 'Műegyetem rkpt. 3.',
 +
                'street2': '2. porta',
 +
                'zip': '1111'
 +
            },
 +
            'tax': '0.0'
 +
        }
  
 +
        // Use one of these to add the event listener to the button click (use only one):
  
'''Table 5: The address value type properties'''
+
        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
 +
        document.getElementById('checkout_button').addEventListener('click', function() {
 +
            bp('track', 'initiateCheckout', initiateCheckoutProperties);
 +
        });
  
{| class="wikitable"
+
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
! Property name
+
        $("#checkout_button").click(function() {
! Property type
+
            bp('track', 'initiateCheckout', initiateCheckoutProperties);
! 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'''
+
    </nowiki>
  
<nowiki>
 
'shippingAddress': {
 
          'deliveryMethod': 'ship',
 
          'country': 'Africa',
 
          'city': 'Egypt',
 
          'region': 'idn',
 
          'zip': '98772',
 
          'street': 'Cleopatra street 24',
 
          'street2': 'Faro street 49',
 
          'fullName': 'Sir Lancelot',
 
          'phone': '+367187242'
 
      }
 
</nowiki>
 
  
== Events related to content browsing ==
+
== Initiate Purchase (initiatePurchase) ==
  
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'''.
+
* Firing event: ''Button click'' that completes the checkout process
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.
+
* User intent: Pay for the items in the cart
 +
* Why do we need this: Users usually are put off by adverts of an item they already purchased, but can be receptive to related products
  
 +
This event should be fired at the same time as the user is redirected to a payment solution's own website, for example
 +
when the user is sent to the Barion Smart Gateway for payment. It should also be fired if the user chose a non-payment
 +
checkout option, for example payment on receipt, but the transaction is considered complete. This should be the last
 +
confirmation of the checkout process, after which the sale is considered to have taken place. Ideally after pressing
 +
this button the user should reach either a 'payment pending' then a 'thank you' page, or simply the 'thank you' page.
  
'''Table 6: Properties of events related to content browsing'''
 
  
 +
'''Initiate purchase event properties'''
 
{| class="wikitable"
 
{| class="wikitable"
!
+
! name
!colspan = "5"| Event
+
! required
 +
! type
 +
! description
 
|-
 
|-
! Property
+
! contents
! contentView
 
! clickProduct
 
! clickProductDetail
 
! customizeProduct
 
! clickPromo
 
|-
 
! contentType
 
| YES
 
| YES
 
| YES
 
| YES
 
 
| YES
 
| YES
 +
| array
 +
| An array of JS objects for detailing the actual items contained in the cart, meaning the shipping and coupons should be excluded. For the detailed format see the table below.
 
|-
 
|-
! id
+
! currency
| YES
+
| NO
| YES
+
| text (ISO 4217)
| YES
+
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
| YES
 
| YES
 
 
|-
 
|-
! name
+
! revenue
| YES
+
| NO
| YES
+
| float
| YES
+
| The total revenue associated with the transaction in the given currency. This should include all costs the customer pays like shipping or tax.
| YES
 
| YES
 
 
|-
 
|-
! unitPrice
+
! step
| YES*
 
 
| YES
 
| YES
| YES
+
| integer
| YES
+
| In most cases, since this is the first checkout step, this should be 0.
|
 
 
|-
 
|-
! unit
+
! contentType
| YES*
+
| NO
| YES
+
| text
| YES
+
| Usually this value should be "Product".
| YES
 
|
 
 
|-
 
|-
! currency
+
! coupon
| YES*
+
| NO
| YES
+
| text
| YES
+
| The coupon code that is being used.
| YES
 
|
 
|-
 
! quantity
 
| YES*
 
| YES
 
|
 
|
 
|
 
|-
 
! variant
 
|
 
|
 
|
 
| YES
 
|
 
 
|-
 
|-
 
! creative
 
! creative
|
+
| NO
|
+
| text
|
+
| The name or description of the promotion for the cart, for example a promotion picture filename or slogan of the promotion that starts the checkout automatically.
|
 
| YES
 
 
|-
 
|-
! contents
+
! customerValue
|
+
| NO
|
+
| float
|
+
| A metric that you define that measures the value of the action performed to your business.
|
 
|
 
 
|-
 
|-
! ean
+
! list
|
+
| NO
|
+
| text
|
+
| In most cases this should be 'Checkout'.
|
 
|
 
 
|-
 
|-
! brand
+
! option
|
+
| NO
|
+
| text
|
+
| Additional information about the purchase.
|
 
|
 
 
|-
 
|-
! category
+
! orderNumber
|
+
| NO
|
+
| text
|
+
| The unique ID of the purchase.
|
 
|
 
|-
 
! list
 
|
 
|
 
|
 
|
 
|
 
 
|-
 
|-
 
! position
 
! position
|
+
| NO
|
+
| text
|
+
| The item's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
|
 
|
 
 
|-
 
|-
! step
+
! shipping
|
+
| NO
|
+
| float
|
+
| The price of shipping associated with the purchase in the given currency.
|
 
|
 
 
|-
 
|-
! customerValue
+
! shippingAddress
|
+
| NO
|
+
| object
|
+
| The shipping address given in the format detailed below.
|
 
|
 
 
|-
 
|-
!
+
! tax
|colspan = "5"| * Required only in case of contentType=Product when using the contentView event.
+
| NO
 +
| float
 +
| The tax associated with the purchase in the given currency.
 
|}
 
|}
  
== Purchase related events ==
 
  
These events refer to purchase intentions and effective checkouts and purchases. These events also share a number of common properties.
+
'''Initiate purchase event implementation example'''
 +
 
 +
    <nowiki>
 +
 
 +
        // sample product data
 +
        var initiatePurchaseProperties = {
 +
            'contents': [{
 +
                'contentType': 'Product',
 +
                'currency': 'HUF',
 +
                'id': 'item_42',
 +
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
                'quantity': 3,
 +
                'totalItemPrice': 7500.0,
 +
                'unit': 'pcs',
 +
                'unitPrice': 2500.0,
 +
                'brand': 'Gollancz',
 +
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
 +
                'ean': 9780575115347,
 +
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
 +
                'variant': 'hardcover'
 +
                },
 +
                {
 +
                'contentType': 'Product',
 +
                'currency': 'USD',
 +
                'id': 'item_42en',
 +
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
                'quantity': 3,
 +
                'totalItemPrice': 25.935,
 +
                'unit': 'pcs',
 +
                'unitPrice': 8.645,
 +
                'brand': 'Gollancz',
 +
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
 +
                'ean': 9780575115347,
 +
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
 +
                'variant': 'hardcover'
 +
                },
 +
            ]
 +
            'currency': 'HUF',
 +
            'revenue': 17500.0,
 +
            'step': 6,
 +
            'contentType': 'Product',
 +
            'coupon': '43763436874'
 +
            'creative': 'preselected_cart_01',
 +
            'customerValue': '150',
 +
            'list': 'Checkout',
 +
            'option': 'To postal office, no street address',
 +
            'orderNumber': 852,
 +
            'position': 1,
 +
            'shipping': 2500.0,
 +
            'shippingAddress': {
 +
                'city': 'Budapest',
 +
                'country': 'HU',
 +
                'deliveryMethod': 'DHL',
 +
                'fullName': 'John Doe',
 +
                'phone': '+36 1 1111 111',
 +
                'region': 'HU-BU',
 +
                'street': 'Műegyetem rkpt. 3.',
 +
                'street2': '2. porta',
 +
                'zip': '1111'
 +
            },
 +
            'tax': '0.0'
 +
        }
 +
 
 +
        // Use one of these to add the event listener to the button click (use only one):
 +
 
 +
        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
 +
        document.getElementById('confirm_payment').addEventListener('click', function() {
 +
            bp('track', 'initiatePurchase', initiatePurchaseProperties);
 +
        });
  
=== addToCart/removeFromCart ===
+
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
 +
        $("#confirm_payment").click(function() {
 +
            bp('track', 'initiatePurchase', initiatePurchaseProperties);
 +
        });
  
Both events have the same event set and the required properties are the same as well.
+
    </nowiki>
  
 +
= Additional Events =
  
'''Table 7: addToCart/removeFromCart event properties'''
+
== Click Product (clickProduct) ==
 +
 
 +
* User intent: View an item
 +
* To be implemented at: Button click on a item
 +
* Why do we need this: Users demonstrate interest in your items by clicking them
 +
 
 +
This event should be fired each time that a user selects any of your items. This could be for example on a product
 +
selection page, a result on a search or filter page, an item on a promotion. The page type on which the button is on
 +
should be specified in the 'list' property. In case of product bundles, you can use the 'contents' property to list each
 +
item in the bundle, while the direct properties should refer to the bundle as a whole as an item.
 +
 
 +
'''Click product event properties'''
  
 
{| class="wikitable"
 
{| class="wikitable"
! Property
+
! name
! Required
+
! required
 +
! type
 +
! description
 
|-
 
|-
 
! contentType
 
! contentType
 
| YES
 
| YES
 +
| text
 +
| The type of the content of the page where the item was selected. Possible values (only these are accepted): Page/Product/Article/Promotion/Banner/Misc.
 
|-
 
|-
 
! currency
 
! currency
 
| YES
 
| YES
 +
| text (ISO 4217)
 +
| Currency that the item is listed in for purchase. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
 
|-
 
|-
 
! id
 
! id
 
| YES
 
| YES
 +
| text
 +
| Unique ID of the item clicked on your site.
 
|-
 
|-
 
! name
 
! name
 
| YES
 
| YES
 +
| text
 +
| Full name of the item clicked.
 
|-
 
|-
 
! quantity
 
! quantity
 
| YES
 
| YES
|-
+
| integer
! totalItemPrice
+
| The quantity of a product clicked measured in the unit provided (e.g. 2).
| YES
 
 
|-
 
|-
 
! unit
 
! unit
 
| YES
 
| YES
 +
| text
 +
| The measurement unit of the item clicked. (e.g. pcs, kg).
 
|-
 
|-
 
! unitPrice
 
! unitPrice
 
| YES
 
| YES
 +
| float
 +
| Price of one unit (that you provided) of the item clicked (in the currency that you provided).
 
|-
 
|-
 
! brand
 
! brand
|
+
| NO
 +
| text
 +
| Brand of the item clicked.
 
|-
 
|-
 
! category
 
! category
|
+
| NO
 +
| text
 +
| The category (eg. 'winter shoes' or 'summer shoes') or subcategory branch (eg. 'clothes|shoes|winter' or 'clothes|shoes|summer', separate levels with '|') of the item clicked.
 
|-
 
|-
 
! contents
 
! contents
|
+
| NO
|-
+
| array
! coupon
+
| An array of JS objects for detailing multiple items clicked. For more details see the table below.
|
 
 
|-
 
|-
 
! creative
 
! creative
|
+
| NO
 +
| text
 +
| The name or description of the promotion for the item, for example a promotion picture filename or slogan of the promotion that selects the item.
 
|-
 
|-
 
! customerValue
 
! customerValue
|
+
| NO
 +
| float
 +
| The value of a user performing this event to the business.
 
|-
 
|-
 
! ean
 
! ean
|
+
| NO
 +
| text
 +
| Contains the International Article Number (EAN) of the item if available.
 
|-
 
|-
 
! list
 
! list
|
+
| NO
 +
| text
 +
| The collection that the product clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
 
|-
 
|-
 
! position
 
! position
|
+
| NO
 +
| text
 +
| The product's position in the list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
 
|-
 
|-
 
! step
 
! step
|
+
| NO
 +
| integer
 +
| A number that represents the progress in the checkout process. Usually at a click product event, this is 0.
 
|-
 
|-
 
! variant
 
! variant
|
+
| NO
 +
| text
 +
| The variant of the product (e.g. 'black') clicked.
 
|}
 
|}
  
=== initiateCheckout, addPaymentInfo, initiatePurchase, purchase ===
+
'''Click product event implementation example'''
  
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.
+
    <nowiki>
  
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.
+
        // sample product data for single product
 +
        var clickProductProperties = {
 +
            'contentType': 'Product',
 +
            'currency': 'HUF',
 +
            'id': 'item_42',
 +
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
            'quantity': 1,
 +
            'unit': 'pcs',
 +
            'unitPrice': 2500.0,
 +
            'brand': 'Gollancz',
 +
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
            'contents': []
 +
            'creative': 'book_42',
 +
            'customerValue': '150.0',
 +
            'ean': 9780575115347,
 +
            'list': 'Checkout',
 +
            'position': 1,
 +
            'step': 2,
 +
            'variant': 'hardcover'
 +
        }
  
  
'''Table 8: Properties of initiateCheckout, addPaymentInfo, initiatePurchase and purchase events'''
+
        // sample product data for bundle offer
 +
        var clickProductProperties = {
 +
            'contentType': 'Product',
 +
            'currency': 'HUF',
 +
            'id': 'item_42pack',
 +
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
            'quantity': 1,
 +
            'unit': 'pcs',
 +
            'unitPrice': 15000.0,
 +
            'brand': 'Gollancz',
 +
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
            'contents': [{
 +
                'contentType': 'Product',
 +
                'currency': 'HUF',
 +
                'id': 'item_42',
 +
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
                'quantity': 3,
 +
                'totalItemPrice': 7500.0,
 +
                'unit': 'pcs',
 +
                'unitPrice': 2500.0,
 +
                'brand': 'Gollancz',
 +
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
 +
                'ean': 9780575115347,
 +
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
 +
                'variant': 'hardcover'
 +
                },
 +
                {
 +
                'contentType': 'Product',
 +
                'currency': 'USD',
 +
                'id': 'item_42en',
 +
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
 +
                'quantity': 3,
 +
                'totalItemPrice': 25.935,
 +
                'unit': 'pcs',
 +
                'unitPrice': 8.645,
 +
                'brand': 'Gollancz',
 +
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
 +
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
 +
                'ean': 9780575115347,
 +
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
 +
                'variant': 'hardcover'
 +
                },
 +
            ]
 +
            'creative': 'bundle_offer_01',
 +
            'customerValue': '150.0',
 +
            'ean': 9780575115347,
 +
            'list': 'Checkout',
 +
            'position': 1,
 +
            'step': 2,
 +
            'variant': 'hardcover'
 +
        }
  
{| class="wikitable"
+
        // Use one of these to add the event listener to the button click (use only one):
!
 
!colspan="4"|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 ===
+
        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
 +
        document.getElementById('book_42').addEventListener('click', function() {
 +
            bp('track', 'clickProduct', clickProductProperties);
 +
        });
  
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.
+
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
 +
        $("#book_42").click(function() {
 +
            bp('track', 'clickProduct', clickProductProperties);
 +
        });
  
 
+
     </nowiki>
'''Table 9: Properties of search event'''
 
 
 
{| class="wikitable"
 
! 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'''
 
 
 
{| class="wikitable"
 
! 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'''
 
 
 
{| class="wikitable"
 
! Key
 
! Required
 
|-
 
! code
 
| YES
 
|-
 
! description
 
| YES
 
|}
 
 
 
'''Figure 9'''
 
 
 
<nowiki>
 
 
 
var errorData = {
 
        'description': 'testError',
 
        'code': 485,
 
     }
 
 
 
    bp('track', 'error', errorData);
 
</nowiki>
 

Revision as of 14:48, 6 May 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). The implementation of the base code is considered mandatory for using the Barion Smart Gateway.


Implementing the base code

Implementing the base code is not only required for you to be considered for special offers relating to the Barion Pixel, but also for using the Barion Smart Gateway at all. This is based on the fact that both Barion and you as the website owner have a legitimate interest in fraud management, and the data provided by the Barion Pixel greatly helps these efforts. This, as a legitimate interest case, is fully compliant with the GDPR, and must be implemented independently of any consent management software that your site may use.

Init

  • User intent: View pages on your site
  • To be implemented at: Every page load, in the document head tag
  • Why do we need this: This provides very basic information on user sessions, and can be implemented very easily

To use the Pixel, you need to 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. Be sure to insert your unique Barion Pixel ID at both locations in the provided code example.

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 data happens asynchronously in the client's browser so that it does not affect user experience.

Implementation of the base code

   
        <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>
    


Heartbeat

  • User intent: Browse your site
  • To be implemented at: No further implementation needed beyond the init event
  • Why do we need this: This provides information on time spent on your various pages

Heartbeat events are sent each minute from each page that the init event is implemented at, as long as the user does not navigate away from the page or the session is not considered timed out. It can provide information about time spent viewing each site by users.


Minimal implementation

To be considered for the special contract terms in connection with the implementation of the Barion Pixel's full marketing capabilities, you have to implement the following events on your site. All events should be implemented in every location applicable, further detailed below. Events may require parameters, which must be included in the bp function call as a JS object. This contains additional information about an event, for example product IDs, categories, and the number of products purchased.


Consent (grantConsent, rejectConsent)

  • User intent: Give or reject Barion Pixel consent
  • To be implemented at: Inside your own consent management software
  • Why do we need this: Participation of webshop clients is entirely consent based complying with the GDPR

Consent events determine which of the sent data can 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. Sending this event must be handled by your own consent management implementation that you are responsible for as outlined in our terms. The "rejectConsent" event should be sent when the customer rejects the cookie policy that includes Barion Pixel functionality. It should be noted that rejecting Barion marketing consent does not mean that no data should be sent towards Barion, as Barion has a legitimate interest using this data for fraud management. Rejecting Barion consent however means that the data from that session will not be used for marketing purposes at all, despite receiving it. All consent events are sent by calling the Pixel's consent function as shown below.

Consent event implementation example

   
        bp('consent', 'grantConsent');
        bp('consent', 'rejectConsent');
    


Content View (contentView)

  • Firing event: Page load of item pages minimally, preferably on all pages that refers to a single item, offer or promotion
  • User intent: View the page that shows a single offer described exclusively
  • Why do we need this: Offer descriptions help us know more about your offers

This event should be fired when one of your users enters a page that refers to one of your items that can be bought, and describes it in general terms, with an offer to buy. This can be something like an offer page on an e-commerce website or a product page on a retail site. It is important to not confuse this with a full product detail page where the product itself is described in greater detail, but there is no information on price, shipping and other details that are relevant to you offer, like in the case of a product manual.


Content view event properties

name required type description
contentType YES text If this is a product page as per minimal requirements, this value should be "Product". Otherwise select a value that best fits from these: Page/Product/Article/Promotion/Banner/Misc.
currency YES (in case of "Product") text (ISO 4217) The currency that the product price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
id YES text An unique ID that you have for the offer, this can be your ID for the product, an SKU or a promotion ID.
name YES text The full name that you have for the offer, for example a product name (eg. Red Bull 24pcs carton).
quantity YES (in case of "Product") float The quantity of the product offered as initially given on the page.
unit YES (in case of "Product") text The unit that your offer is measured in (eg. pieces, kg, m).
unitPrice YES (in case of "Product") float The price of one measurement of your offer in the given currency.
brand NO text The brand of the offer.
category NO text The subcategory branch (preferred, eg. 'clothes|shoes|winter', separate levels with '|') or single category (eg. 'winter shoes' or 'summer shoes') of the offer.
contents NO array An array of JS objects for detailing multiple items of the offer. For more details see the table below.
creative NO text The name or description of the promotion, for example a promotion picture filename or slogan.
customerValue NO float A metric that you define that measures the value of the action performed to your business.
ean NO text Contains the International Article Number (EAN) of the offer if available.
list NO text THe function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
position NO text The product's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
step NO integer If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 0 as the checkout initiation.
variant NO text THe variant of the offer from the list of possible identical items (eg. the color of a phone or the time and venue of a concert or movie)


Content view event implementation example

   

        // example properties for a product page
        var contentViewProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': '10',
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'contents': undefined,
            'creative': undefined,
            'customerValue': '150',
            'ean': 9780575115347,
            'list': 'ProductPage',
            'position': undefined,
            'step': undefined,
            'variant': 'hardcover'
        }

        // example properties on a home page for a promotion of a product
        var contentViewProperties = {
            'contentType': 'Promotion',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': '10',
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'contents': undefined,
            'creative': 'book_promo_02',
            'customerValue': '150',
            'ean': 9780575115347,
            'list': 'HomePage',
            'position': 2,
            'step': undefined,
            'variant': 'hardcover'
        }

        // example properties on a checkout page for a promotion of a product
        var contentViewProperties = {
            'contentType': 'Promotion',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': '10',
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'contents': undefined,
            'creative': 'also_bought_05',
            'customerValue': '150',
            'ean': 9780575115347,
            'list': 'Checkout',
            'position': 5,
            'step': 2,
            'variant': 'hardcover'
        }

        // Use one of these to add the event listener to the button click (use only one):

        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
        window.addEventListener('onload', function() {
            bp('track', 'contentView', contentViewProperties);
        });

        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("window").load(function() {
            bp('track', 'contentView', contentViewProperties);
        });

    


Add to Cart (addToCart)

  • Firing event: Button click that results in a product to be selected for purchase
  • User intent: Select product for purchase
  • Why do we need this: Users demonstrate strong interest in your items by selecting them for purchase

The add to cart event is, as its name suggests, connected to a user "adding a product to their cart". Usually this means that a user decide to purchase a product or service, and has added this item to their cart. Even if your website does not use carts in the literal sense, there is a point in a user session where the given user decides that they intend to purchase the product. This exact intent is what we want to capture here, so the button click which best matches the point of this intent, such as one labeled 'Buy' or 'Reserve' should be the one to attach this event to.


Add to cart event properties

name required type description
contentType YES text Usually, this value should be "Product".
currency YES text (ISO 4217) The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
id YES text An unique ID that you have for the item, this can be your ID for the product, an SKU or a promotion ID.
name YES text The full name that you have for the added item, for example a product name (eg. Red Bull 24pcs carton).
quantity YES float The quantity of the item added to the cart.
totalItemPrice YES float The total price of the added items in the given currency.
unit YES text The unit that your item is measured in (eg. pieces, kg, hours).
unitPrice YES float The price of one measurement of your item in the given currency.
brand NO text The brand of the item.
category NO text The subcategory branch (preferred, eg. 'clothes|shoes|winter', separate levels with '|') or single category (eg. 'winter shoes' or 'summer shoes') of the item.
coupon NO text The coupon code that was used when the item was added to cart.
contents NO array An array of JS objects for detailing multiple items of the item. For more details see the table below.
creative NO text The name or description of the promotion for the item, for example a promotion picture filename or slogan of the promotion that adds the items to the cart automatically.
customerValue NO float A metric that you define that measures the value of the action performed to your business.
ean NO text Contains the International Article Number (EAN) of the offer if available.
list NO text THe function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
position NO text The item's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
step NO integer If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 0 as the checkout initiation.
variant NO text THe variant of the offer from the list of possible identical items (eg. the color of a phone or the time and venue of a concert or movie)


Add to cart event implementation example

   

        // sample product data
        var addToCartProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': '10',
            'totalItemPrice': 49900.0,
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'contents': undefined,
            'coupon': '43763436874'
            'creative': undefined,
            'customerValue': '150',
            'ean': 9780575115347,
            'list': 'ProductPage',
            'position': undefined,
            'step': undefined,
            'variant': 'hardcover'
        }

        // Use one of these to add the event listener to the button click (use only one):

        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
        document.getElementById('addtocart_button').addEventListener('click', function() {
            bp('track', 'addToCart', addToCartProperties);
        });

        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#addtocart_button").click(function() {
            bp('track', 'addToCart', addToCartProperties);
        });

    


Initiate Checkout (initiateCheckout)

  • Firing event: Button click that starts the checkout process
  • User intent: Purchase the items in the cart
  • Why do we need this: Users usually are put off by adverts of an item they already purchased, but can be receptive to related products

Usually on a webshop, there is a checkout process that starts with clicking a button with items in your cart. This button click is the one that this event should be attached to. After this click, typically the user has to provide other data, such as a shipping address and method, and confirm the purchase (which should fire the initiate purchase event).


Initiate checkout event properties

name required type description
contents YES array An array of JS objects for detailing the actual items contained in the cart, meaning the shipping and coupons should be excluded. For the detailed format see the table below.
currency YES text (ISO 4217) The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
revenue YES float The total revenue associated with the transaction in the given currency. This should include all costs the customer pays like shipping or tax.
step YES integer In most cases, since this is the first checkout step, this should be 0.
contentType NO text Usually this value should be "Product".
coupon NO text The coupon code that is being used.
creative NO text The name or description of the promotion for the cart, for example a promotion picture filename or slogan of the promotion that starts the checkout automatically.
customerValue NO float A metric that you define that measures the value of the action performed to your business.
list NO text In most cases this should be 'Checkout'.
option NO text Additional information about the purchase.
orderNumber NO text The unique ID of the purchase.
position NO text The item's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
shipping NO float The price of shipping associated with the purchase in the given currency.
shippingAddress NO object The shipping address given in the format detailed below.
tax NO float The tax associated with the purchase in the given currency.


Initiate checkout event implementation example

   

        // sample product data
        var initiateCheckoutProperties = {
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
                'ean': 9780575115347,
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
                'variant': 'hardcover'
                },
                {
                'contentType': 'Product',
                'currency': 'USD',
                'id': 'item_42en',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3,
                'totalItemPrice': 25.935,
                'unit': 'pcs',
                'unitPrice': 8.645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
                'ean': 9780575115347,
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
                'variant': 'hardcover'
                },
            ]
            'currency': 'HUF',
            'revenue': 17500.0,
            'step': 0,
            'contentType': 'Product',
            'coupon': '43763436874'
            'creative': 'preselected_cart_01',
            'customerValue': '150',
            'list': 'Checkout',
            'option': 'To postal office, no street address',
            'orderNumber': 852,
            'position': 1,
            'shipping': 2500.0,
            'shippingAddress': {
                'city': 'Budapest',
                'country': 'HU',
                'deliveryMethod': 'DHL',
                'fullName': 'John Doe',
                'phone': '+36 1 1111 111',
                'region': 'HU-BU',
                'street': 'Műegyetem rkpt. 3.',
                'street2': '2. porta',
                'zip': '1111'
            },
            'tax': '0.0'
        }

        // Use one of these to add the event listener to the button click (use only one):

        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
        document.getElementById('checkout_button').addEventListener('click', function() {
            bp('track', 'initiateCheckout', initiateCheckoutProperties);
        });

        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#checkout_button").click(function() {
            bp('track', 'initiateCheckout', initiateCheckoutProperties);
        });

    


Initiate Purchase (initiatePurchase)

  • Firing event: Button click that completes the checkout process
  • User intent: Pay for the items in the cart
  • Why do we need this: Users usually are put off by adverts of an item they already purchased, but can be receptive to related products

This event should be fired at the same time as the user is redirected to a payment solution's own website, for example when the user is sent to the Barion Smart Gateway for payment. It should also be fired if the user chose a non-payment checkout option, for example payment on receipt, but the transaction is considered complete. This should be the last confirmation of the checkout process, after which the sale is considered to have taken place. Ideally after pressing this button the user should reach either a 'payment pending' then a 'thank you' page, or simply the 'thank you' page.


Initiate purchase event properties

name required type description
contents YES array An array of JS objects for detailing the actual items contained in the cart, meaning the shipping and coupons should be excluded. For the detailed format see the table below.
currency NO text (ISO 4217) The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
revenue NO float The total revenue associated with the transaction in the given currency. This should include all costs the customer pays like shipping or tax.
step YES integer In most cases, since this is the first checkout step, this should be 0.
contentType NO text Usually this value should be "Product".
coupon NO text The coupon code that is being used.
creative NO text The name or description of the promotion for the cart, for example a promotion picture filename or slogan of the promotion that starts the checkout automatically.
customerValue NO float A metric that you define that measures the value of the action performed to your business.
list NO text In most cases this should be 'Checkout'.
option NO text Additional information about the purchase.
orderNumber NO text The unique ID of the purchase.
position NO text The item's position in a list or collection (e.g. 2) or the position of the promotion on a page (e.g. banner_slot_1).
shipping NO float The price of shipping associated with the purchase in the given currency.
shippingAddress NO object The shipping address given in the format detailed below.
tax NO float The tax associated with the purchase in the given currency.


Initiate purchase event implementation example

   

        // sample product data
        var initiatePurchaseProperties = {
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
                'ean': 9780575115347,
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
                'variant': 'hardcover'
                },
                {
                'contentType': 'Product',
                'currency': 'USD',
                'id': 'item_42en',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3,
                'totalItemPrice': 25.935,
                'unit': 'pcs',
                'unitPrice': 8.645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
                'ean': 9780575115347,
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
                'variant': 'hardcover'
                },
            ]
            'currency': 'HUF',
            'revenue': 17500.0,
            'step': 6,
            'contentType': 'Product',
            'coupon': '43763436874'
            'creative': 'preselected_cart_01',
            'customerValue': '150',
            'list': 'Checkout',
            'option': 'To postal office, no street address',
            'orderNumber': 852,
            'position': 1,
            'shipping': 2500.0,
            'shippingAddress': {
                'city': 'Budapest',
                'country': 'HU',
                'deliveryMethod': 'DHL',
                'fullName': 'John Doe',
                'phone': '+36 1 1111 111',
                'region': 'HU-BU',
                'street': 'Műegyetem rkpt. 3.',
                'street2': '2. porta',
                'zip': '1111'
            },
            'tax': '0.0'
        }

        // Use one of these to add the event listener to the button click (use only one):

        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
        document.getElementById('confirm_payment').addEventListener('click', function() {
            bp('track', 'initiatePurchase', initiatePurchaseProperties);
        });

        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#confirm_payment").click(function() {
            bp('track', 'initiatePurchase', initiatePurchaseProperties);
        });

    

Additional Events

Click Product (clickProduct)

  • User intent: View an item
  • To be implemented at: Button click on a item
  • Why do we need this: Users demonstrate interest in your items by clicking them

This event should be fired each time that a user selects any of your items. This could be for example on a product selection page, a result on a search or filter page, an item on a promotion. The page type on which the button is on should be specified in the 'list' property. In case of product bundles, you can use the 'contents' property to list each item in the bundle, while the direct properties should refer to the bundle as a whole as an item.

Click product event properties

name required type description
contentType YES text The type of the content of the page where the item was selected. Possible values (only these are accepted): Page/Product/Article/Promotion/Banner/Misc.
currency YES text (ISO 4217) Currency that the item is listed in for purchase. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
id YES text Unique ID of the item clicked on your site.
name YES text Full name of the item clicked.
quantity YES integer The quantity of a product clicked measured in the unit provided (e.g. 2).
unit YES text The measurement unit of the item clicked. (e.g. pcs, kg).
unitPrice YES float Price of one unit (that you provided) of the item clicked (in the currency that you provided).
brand NO text Brand of the item clicked.
category NO text shoes|winter' or 'clothes|shoes|summer', separate levels with '|') of the item clicked.
contents NO array An array of JS objects for detailing multiple items clicked. For more details see the table below.
creative NO text The name or description of the promotion for the item, for example a promotion picture filename or slogan of the promotion that selects the item.
customerValue NO float The value of a user performing this event to the business.
ean NO text Contains the International Article Number (EAN) of the item if available.
list NO text The collection that the product clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
position NO text The product's position in the list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
step NO integer A number that represents the progress in the checkout process. Usually at a click product event, this is 0.
variant NO text The variant of the product (e.g. 'black') clicked.

Click product event implementation example

   

        // sample product data for single product
        var clickProductProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': 1,
            'unit': 'pcs',
            'unitPrice': 2500.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'contents': []
            'creative': 'book_42',
            'customerValue': '150.0',
            'ean': 9780575115347,
            'list': 'Checkout',
            'position': 1,
            'step': 2,
            'variant': 'hardcover'
        }


        // sample product data for bundle offer
        var clickProductProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42pack',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': 1,
            'unit': 'pcs',
            'unitPrice': 15000.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
                'ean': 9780575115347,
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
                'variant': 'hardcover'
                },
                {
                'contentType': 'Product',
                'currency': 'USD',
                'id': 'item_42en',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3,
                'totalItemPrice': 25.935,
                'unit': 'pcs',
                'unitPrice': 8.645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhiker's Guide to the Galaxy[1] (sometimes referred to as HG2G,[2] HHGTTG,[3] H2G2,[4] or tHGttG) is a comedy science fiction series created by Douglas Adams.'
                'ean': 9780575115347,
                'imageURL': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
                'variant': 'hardcover'
                },
            ]
            'creative': 'bundle_offer_01',
            'customerValue': '150.0',
            'ean': 9780575115347,
            'list': 'Checkout',
            'position': 1,
            'step': 2,
            'variant': 'hardcover'
        }

        // Use one of these to add the event listener to the button click (use only one):

        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
        document.getElementById('book_42').addEventListener('click', function() {
            bp('track', 'clickProduct', clickProductProperties);
        });

        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#book_42").click(function() {
            bp('track', 'clickProduct', clickProductProperties);
        });