Barion Pixel API reference: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
VisualWikitext
No edit summary
 
(90 intermediate revisions by 7 users not shown)
Line 1: Line 1:
{{PageTitle|title=Barion Pixel}}
{{PageTitle|title=Barion Pixel API reference}}


{| style="margin-left:2em;" align="right"
{| style="margin-left:2em;" align="right"
Line 5: Line 5:
|}
|}


The Barion Pixel is JavaScript code that allows you to track visitor activity on your website. It works by loading a
== Consent (grantConsent, rejectConsent) ==
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:
* User intent: Give or reject Barion Pixel consent
* access to your website's HTML code base
* To be implemented at: Inside your own consent management software
* your Barion Pixel ID that you can access from your Barion Wallet
* Why do we need this: Participation of webshop clients is entirely consent based complying with the GDPR


By default, the Pixel will track pages visited, and the devices your visitors use. In addition, you can use the
Consent events determine which of the sent data can be used by us for marketing purposes. Two consent events can be
Pixel's JavaScript function to track other events that are associated with webshop usage and e-commerce. Without
used to control user consent. The "grantConsent" event has to be sent when the visitor accepts the cookie policy
collecting the consent of the website visitor you must still use the Barion Pixel on your website for fraud management
that expressly allows Barion to use data for marketing purposes. Sending this event must be handled by your own consent
purposes. (Tracking visitor behavior for the purposes of preventing fraud is considered a legitimate interest of
management implementation that you are responsible for as outlined in our terms. The "rejectConsent" event should be
Barion and the merchant in contract with Barion). If you collect the consent of your visitors (see consent events
sent when the customer rejects the cookie policy that includes Barion Pixel functionality. It should be noted that
below in Minimum requirements) for marketing purposes, you can get lower fees for your Barion Smart Gateway. The
rejecting Barion marketing consent does not mean that no data should be sent towards Barion, as Barion has a legitimate
implementation of the base code is considered mandatory for using the Barion Smart Gateway.
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. Usage of a fully compliant consent management platform (CMP) is strongly recommended by Barion. You can find our recommendation [https://docs.barion.com/Barion_Pixel_Consent_Management_requirements here]


= Implementing the base code =


== Base code ==
To install the Pixel, we highly recommend that you add the following code (referred to as the base code) between the
opening and closing <head> tags on every page of your site. Most developers add it to their website's persistent header,
so that it appears automatically on all loaded pages.


Placing the code within your <head> tags reduces the chances of browsers or third-party code blocking the Pixel's
'''Consent event implementation example'''
execution. It also executes the code sooner, increasing the chance that your visitors are tracked before they leave your
page. Sending the tracking data happens asynchronously in the client's browser so that it does not slow user experience.
 
'''Figure 1'''


     <nowiki>
     <nowiki>
        bp('consent', 'grantConsent');
        bp('consent', 'rejectConsent');
    </nowiki>


        <script>
== Encrypting personal data (setEncryptedEmail, setEncryptedPhone) ==


            (function(i,s,o,g,r,a,m){i['BarionAnalyticsObject']=r;i[r]=i[r]||function(){
* Firing event: On click or per pageview when email / phone number is globally or occasionally available for the given user.
            (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
* User intent: User types in their email (or phone number) for any reason, such as signing in, within checkout when placing an order, signig up for newsletter, etc.
            m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
* Why do we need this: More accurate data collection after third party cookie phase out in compliance with GDPR.
            })(window, document, 'script', 'https://pixel.barion.com/bp.js', 'bp');


            // send page view event
We do not collect unencrypted personally identifiable information (PII). All PII data is encrypted by the SHA-1 algorithm that hides the real, human readable email address and phone number.
            bp('init', 'addBarionPixelId', '[Your Barion Pixel ID goes here]');
The encryption process will always happen on Barion side whenever an unencrypted email address (or phone number) is being sent but it is also possible to send a previously SHA-1 encrypted email address (or phone number). Sending an empty string, invalid email address (or phone number) or a not properly hashed value will result in an error message.
'''Please send email with lowercase letter and the phone number as customer type in.'''


        </script>


        <noscript>
'''setEncryptedEmail / setEncryptedPhone implementation example'''


            <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"/>
    <nowiki>
        bp('identity','setEncryptedEmail', 'sample.steve@gmail.com');
        bp('identity','setEncryptedPhone', '+36301234567');
    </nowiki>
OR
    <nowiki>
        var hashedEmailAddress = sha1('sample.[email protected]');
        bp('identity','setEncryptedEmail', hashedEmailAddress);


         </noscript>
         var hashedPhone = sha1('+36301234567');
        bp('identity','setEncryptedPhone', hashedPhone);


     </nowiki>
     </nowiki>


When run, this code will make available a JavaScript function which you can then use for tracking. It also automatically
== Content View (contentView) ==
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 ==
* Firing event: ''Page load'' of item pages minimally, preferably on all pages that refers to a single item or other information.
Consent events determine which of the sent data could be used by us for marketing purposes. Two consent events can be
* User intent: View the page that shows a single offer described exclusively or retrieve any information about something.
used to control user consent. The "grantConsent" event has to be sent when the visitor accepts the cookie policy
* Why do we need this: Offer descriptions help us know more about your offers and ecommerce behaviour.
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'''


    <nowiki>
This event should be fired when one of your users visit a page that refers to one of your items that can be bought
or users read other information about something that is not connected to an item directly (e.g.: news, description, articles, blog posts etc.). Except product page, in most cases the page title is adequate for ''name'' property.


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


    </nowiki>
''' Content view event properties  '''
{| class="wikitable"
! key
! 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) in product page, otherwise in most cases page title is adequate. Please note that item names should be consistent in all events.
|-
! 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.
|-
! [[#Special_properties|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.
|-
! imageUrl
| NO
| text
| The URL of the image of the viewed item.
|-
! list
| NO
| text
| The function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
|-
! positioning
| 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 1 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)
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>


= Implementing Standard and Custom Events =
There are two ways to track conversions with the Pixel:
* standard events, which are visitor actions that we have defined and that you report by calling a Pixel function
* custom events, which are visitor actions that you have defined and that you report by calling a Pixel function


== Standard Events ==
''' Content view event implementation examples: '''
Standard events are predefined visitor actions that correspond to common conversion-related activities, such as
searching for a product, viewing a product, or purchasing a product. Standard events require parameters, which must be
included in the bp function call parameters as an object containing additional information about an event, such as
product IDs, categories, and the number of products purchased. Some events have mandatory properties (see below). In
order to track an event, the code tracking the event needs to be added with its properties into your page JavaScript
either through a <script> tag or sourced JS files.


All standard events are tracked by calling the Pixel's bp('track') function, with the event name, and a JSON object as
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
its parameters.
| <strong> For physical items </strong>
|-
|  // 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.0,
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'imageUrl': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
            'list': 'ProductPage',
            'variant': 'hardcover'
        }


'''Figure 3'''
        // 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.0,
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'creative': 'book_promo_02',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'imageUrl': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
            'list': 'HomePage',
            'positioning': '2',
            'variant': 'hardcover'
        }


    <nowiki>
        // 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.0,
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'creative': 'also_bought_05',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'imageUrl': 'https://images-na.ssl-images-amazon.com/images/I/51MzUz8rQcL._SX305_BO1,204,203,200_.jpg',
            'list': 'Checkout',
            'positioning': '5',
            'step': 2,
            'variant': 'hardcover'
        }


    // contentView event tracking example
    var contentViewProperties = {
        'id': 'promo01',
        'contentType': 'Promotion',
        'name': 'Winter tires 20% off',
    }


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


    </nowiki>
|}


Sometimes you may want to track this event when a specific button is clicked. This can be achieved as in the example
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
below (note that you may use technologies that require different syntax, like the below example using jQuery). Note that
| <strong> For ticket sellers </strong>
the Pixel base code needs to be included in the page in order to be able to track events.
|-
|  // example properties for a product page
        var contentViewProperties = {
            'contentType': 'Product',
            'currency': 'GBP',
            'id': 'metalica_12',
            'name': 'Metallica',
            'quantity': 1.0,
            'unit': 'pcs.',
            'unitPrice': 300.0,
            'category': 'Pop|Metal',
            'customerValue': 150.0,
            'imageUrl': "https://www.revolvermag.com/sites/default/files/styles/image_954_x_537/public/media/images/article/metallicapr.jpg",
            'list': 'ProductPage',
            'variant': '2019.06.08 20:00|Slane Castle'
        }


'''Figure 4'''
        // example properties on a home page for a promotion of a product
        var contentViewProperties = {
            'contentType': 'Promotion',
            'currency': 'GBP',
            'id': 'metalica_12',
            'name': 'Metallica',
            'quantity': 1.0,
            'unit': 'pcs.',
            'unitPrice': 300.0,
            'category': 'Pop|Metal',
            'creative': 'metallica_promo_02',
            'customerValue': 150.0,
            'imageUrl': "https://www.revolvermag.com/sites/default/files/styles/image_954_x_537/public/media/images/article/metallicapr.jpg",
            'list': 'HomePage',
            'positioning': '2',
            'variant': '2019.06.08 20:00|Slane Castle'
        }


    <nowiki>
         // example properties on a checkout page for a promotion of a product
 
         var contentViewProperties = {
         // sample product data
             'contentType': 'Promotion',
         var addToCartProperties = {
            'currency': 'GBP',
             'id': 'item001',
             'id': 'metalica_12',
             'contentType': 'Page',
             'name': 'Metallica',
             'name': 'first',
             'quantity': 1.0,
             'ean': '9501101530003',
            'unit': 'pcs.',
             'unitPrice': 1000,
             'unitPrice': 300.0,
             'totalItemPrice': 2000,
             'category': 'Pop|Metal',
             'unit': 'kg',
             'creative': 'also_bought_05',
             'currency': 'huf',
            'customerValue': 150.0,
             'quantity': 2,
            'imageUrl': "https://www.revolvermag.com/sites/default/files/styles/image_954_x_537/public/media/images/article/metallicapr.jpg",
            'list': 'Checkout',
             'positioning': '5',
             'step': 2,
            'variant': '2019.06.08 20:00|Slane Castle'
         }
         }


        // tracking the event
        document.getElementById('addtocart_button').addEventListener('click', function() {
            bp('track', 'addToCart', addToCartProperties);
        });


    </nowiki>
        bp('track', 'contentView', contentViewProperties);


Tracking the same event with jQuery:
|}


    <nowiki>
== Add to Cart (addToCart) ==
 
        // 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
* Firing event: ''Button click'' that results in a product to be selected for purchase
        $("#addtocart_button").click(function() {
* User intent: Select product for purchase
            bp('track', 'addToCart', addToCartProperties);
* Why do we need this: Users demonstrate strong interest in your items by selecting them for purchase
        });


    </nowiki>
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.


== Standard event descriptions ==


With these standard events you can describe a lot of ecommerce related user actions in a meaningful way. Each event has
its own set of properties that is needed in order to fully understand and record the users' intentions.
'''Table 1: Event descriptions'''


'''Add to cart event properties'''
{| class="wikitable"
{| class="wikitable"
! Event name
! key
! Description
! required
! Typical use cases
! type
! description
|-
! contentType
| YES
| text
| Usually, this value should be "Product".
|-
|-
! [[#User_Properties|setUserProperties]]
! currency
| With this event One can add user related information.
| YES
| Registration, login, account details in chechkout step, sign up for newsletter, contact request
| text (ISO 4217)
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
|-
|-
! [[#Events_related_to_content_browsing|contentView]]
! id
| 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
| E.g. product details in product page.
| text
| An unique ID that you have for the item, this can be your ID for the product (e.g. SKU)
|-
|-
! [[#Events_related_to_content_browsing|clickProduct]]
! name
| 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
| The full name that you have for the added item, for example a product name (eg. Red Bull 24pcs carton).
|-
|-
! [[#Events_related_to_content_browsing|clickProductDetail]]
! quantity
| 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
| float
| The quantity of the item added to the cart.
|-
|-
! [[#Events_related_to_content_browsing|customizeProduct]]
! totalItemPrice
| When a person customizes a product. (color, size, etc). Typically fired at user click.
| YES
| E.g. radio button about color on product page
| float
| The total price of the added items in the given currency.
|-
|-
! [[#Events_related_to_content_browsing|clickPromo]]
! unit
| A click on an internal promotion. Fired at mouse click.
| YES
| 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 item is measured in (eg. pieces, kg, hours).
|-
|-
! [[#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
|
| float
| The price of one measurement of your item 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 item.
|-
|-
! [[#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 item.
|-
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|addPaymentInfo]]
! [[#Special_properties|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 item. For more details see the table below.
|-
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|initiatePurchase]]
! coupon
| A person clicks on a purchase button (and possibly enters the Thank You Page).
| NO
|
| text
| The coupon code that was used when the item was added to cart.
|-
|-
! [[#initiateCheckout.2C_addPaymentInfo.2C_initiatePurchase.2C_purchase|purchase]]
! creative
| 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.
| 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.
|-
|-
! [[#Search_event|search]]
! customerValue
| 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.)
| float
| A metric that you define that measures the value of the action performed to your business.
|-
|-
! [[#signUp_event|signUp]]
! ean
| 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
| Contains the International Article Number (EAN) of the offer if available.
|-
|-
! [[#error_event|error]]
! list
| If one want to track errors this event may be used for that.
| NO
|
| text
| The function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
|-
! positioning
| NO
| text
| The item's position in a list or collection (e.g. 2).
|-
! step
| NO
| integer
| If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 1 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)
|}
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>


== 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.
''' Add to cart event implementation examples: '''


'''Figure 5: Custom event tracking'''
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
<nowiki>
| <strong> For physical items </strong>
|-
|  // sample product data for single items
        var addToCartProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': 10.0,
            'totalItemPrice': 49900.0,
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'coupon': '43763436874',
            'creative': 'product_page_promo_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'ProductPage',
            'positioning': '3',
            'variant': 'hardcover'
        }


// sample customData
        // sample product data for bundled items
var customData = {
        var addToCartProperties = {
    eventCategory: 'Video',
            'contentType': 'Product',
    eventAction: 'play',
            'currency': 'HUF',
    eventProperty: 'video',
            'id': 'item_42pack',
    eventLabel: 'Fall Campaign',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
    eventValue: 42
            'quantity': 10.0,
}
            'totalItemPrice': 150000.0,
            '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.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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'
                }],
            'coupon': '43763436874',
            'creative': 'add_to_cart_promo_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'BasketPage',
            'positioning': '3',
            'variant': 'hardcover'
        }


bp('track', 'customEvent', customData);
        // Use one of these to add the event listener to the button click (use only one):
</nowiki>


'''Figure 6: Custom event tracking'''
        // 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);
        });


<nowiki>
         // jQuery (if you use jQuery, if in your console "$" is defined on your site)
var contentViewProperties = {
         $("#addtocart_button").click(function() {
         'id': 'My blog page',
            bp('track', 'addToCart', addToCartProperties);
         'contentType': 'Page',
         });
        'name': 'Very cool product',
         '_mycustomparameter': 42
    }


    bp('track', 'contentView', contentViewProperties);
|}
</nowiki>


{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For ticket sellers </strong>
|-
|    // sample product data for single items
        var addToCartProperties = {
            'contentType': 'Product',
            'currency': 'GBP',
            'id': 'metalica_12',
            'name': 'Metallica',
            'quantity': 2.0,
            'totalItemPrice': 600.0,
            'unit': 'pcs.',
            'unitPrice': 300.0,
            'category': 'Pop|Metal',
            'coupon': '43763436874',
            'creative': 'product_page_promo_metallica',
            'customerValue': 150.0,
            'list': 'ProductPage',
            'positioning': '3',
            'variant': '2019.06.08 20:00|Slane Castle'
        }


        // sample product data for bundled items
        var addToCartProperties = {
            'contentType': 'Product',
            'currency': 'GBP',
            'id': 'spring_festival_two_tickets',
            'name': "Spring Festival ticket",
            'quantity': 2.0,
            'totalItemPrice': 1800.0,
            'unit': 'pcs.',
            'unitPrice': 900.0,
            'category': 'Festival',
            'contents': [{
                'contentType': 'Product',
                'currency': 'GBP',
                'id': 'metalica_12',
                'name': 'Metallica',
                'quantity': 2.0,
                'totalItemPrice': 800.0,
                'unit': 'pcs',
                'unitPrice': 400.0,
                'category': 'Pop|Metal',
                'description': 'Early Bird',
                'imageUrl': "https://www.revolvermag.com/sites/default/files/styles/image_954_x_537/public/media/images/article/metallicapr.jpg",
                'variant': '2019.06.08 20:00|Slane Castle'
                },
                {
                'contentType': 'Product',
                'currency': 'GBP',
                'id': 'snoop_dog_2019',
                'name': "Snoop Dog",
                'quantity': 2.0,
                'totalItemPrice': 1000.0,
                'unit': 'pcs',
                'unitPrice': 500,
                'category': 'Rap',
                'description': 'Early Bird',
                'imageUrl': 'https://cdn1.thr.com/sites/default/files/2012/08/snoop-dogg-pr-08-p.jpg',
                'variant': '2019.06.08 20:00|Slane Castle'
                }],
            'coupon': '43763436874',
            'creative': 'add_to_cart_promo_42',
            'customerValue': 150.0,
            'list': 'BasketPage',
            'positioning': '3',
            'variant': '2019.06.08 20:00|Slane Castle'
        }


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


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.
        // 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);
        });


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.
        // 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) ==


=== Standard properties ===
* 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


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




'''Table 2: Standard properties'''


'''Initiate checkout event properties'''
{| class="wikitable"
{| class="wikitable"
! name
! key
! required
! type
! type
! description
! description
|-
|-
! id
! [[#Special_properties|contents]]
| text
| YES
| SKU of product/id of article/the promotion ID/etc.
| 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 is not include all costs the customer pays like shipping or any discount.
|-
! step
| YES
| integer
| In most cases, since this is the first checkout step, this should be 1.
|-
|-
! contentType
! contentType
| NO
| 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
! coupon
| NO
| text
| text
| Full name of product/article/promotion etc (e.g. Android T-Shirt or e.g. Summer Sale)
| The coupon code that is being used.
|-
|-
! ean
! creative
| NO
| text
| text
| Contains the International Article Number (EAN) when applicable.
| 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.
|-
|-
! brand
! customerValue
| NO
| float
| A metric that you define that measures the value of the action performed to your business.
|-
! list
| NO
| text
| text
| Brand part of product/brand described in name
| In most cases this should be 'Checkout'.
|-
|-
! category
! opt
| 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".
| Additional information about the purchase.
|-
|-
! variant
! orderNumber
| NO
| text
| text
| The variant of the product (e.g. Black)
| The unique ID of the purchase.
|-
|-
! description
! positioning
| NO
| text
| text
| The detailed description of the item.
| 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).
|-
|-
! imageUrl
! shipping
| text
| NO
| A URL pointing to an image that shows the item. E.g. the picture of the product
| float
| The price of shipping associated with the purchase in the given currency.
|-
|-
! unit
! shippingAddress
| text
| NO
| The measurement unit of the item. (e.g. pcs, litre)
| object
| The shipping address given in the format detailed below.
|-
|-
! unitPrice
! tax
| NO
| float
| float
| Price of product (the price of one measurement unit of the item).
| The tax associated with the purchase in the given currency.
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Initiate checkout event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items </strong>
|-
|  // sample product data
        var initiateCheckoutProperties = {
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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': 1,
            'contentType': 'Product',
            'coupon': '43763436874',
            'creative': 'preselected_cart_01',
            'customerValue': 150.0,
            'list': 'Checkout',
            'opt': 'To postal office, no street address',
            'orderNumber': '852',
            'positioning': '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',
                'zipCode': '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);
        });
 
|}
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For ticket sellers </strong>
|-
|      // sample product data
        var initiateCheckoutProperties = {
            'contents': [{
                'contentType': 'Product',
                'currency': 'GBP',
                'id': 'metalica_12',
                'name': 'Metallica',
                'quantity': 2.0,
                'totalItemPrice': 600.0,
                'unit': 'pcs',
                'unitPrice': 300.0,
                'category': 'Pop|Metal',
                'description': 'Early Bird',
                'ean': '9780575115347',
                'imageUrl': 'https://www.revolvermag.com/sites/default/files/styles/image_954_x_537/public/media/images/article/metallicapr.jpg',
                'variant': '2019.06.08 20:00|Slane Castle'
                },
                {
                'contentType': 'Product',
                'currency': 'GBP',
                'id': 'snoop_dog_2019',
                'name': "Snoop Dog",
                'quantity': 3.0,
                'totalItemPrice': 1500.0,
                'unit': 'pcs',
                'unitPrice': 500,
                'category': 'Rap',
                'description': 'Early Bird',
                'ean': '9780575115347',
                'imageUrl': 'https://cdn1.thr.com/sites/default/files/2012/08/snoop-dogg-pr-08-p.jpg',
                'variant': '2019.04.02 23:00|Wembley'
                }],
            'currency': 'GBP',
            'revenue': 2100.0,
            'step': 1,
            'contentType': 'Product',
            'coupon': '43763436874',
            'creative': 'preselected_cart_01',
            'customerValue': 150.0,
            'list': 'Checkout',
            'opt': 'To postal office, no street address',
            'orderNumber': '852',
            'positioning': '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',
                'zipCode': '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'''
{| class="wikitable"
! key
! required
! type
! description
|-
|-
! totalItemPrice
! [[#Special_properties|contents]]
| float
| YES
| The total price of the item.
| 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
! currency
| text (ISO 4217 format)
| YES
| Currency of product. 3 digit ISO-4217 format is preferred.
| 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, tax or any discount.
|-
|-
! quantity
! step
| YES
| integer
| integer
| The quantity of a product (e.g. 2)
| It is its sequential number in checkout process.
|-
|-
! contents
! contentType
| item_list
| NO
| 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
| Usually this value should be "Product".
|-
|-
! position
! coupon
| 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 coupon code that is being used.
|-
|-
! creative
! creative
| NO
| text
| text
| The creative associated with the promotion (e.g. summer_banner2)
| 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.
|-
|-
! step
! customerValue
| integer
| NO
| 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)
| 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'.
|-
|-
! coupon
! opt
| NO
| text
| text
| The transaction coupon code redeemed with the transaction.
| Additional information about the purchase.
|-
|-
! orderNumber
! orderNumber
| NO
| text
| text
| Required if the action is purchase.
| The unique ID of the purchase.
|-
|-
! revenue
! positioning
| 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.
| 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).
! tax
| float
| The total tax associated with the transaction
|-
|-
! shipping
! shipping
| NO
| float
| float
| The shipping cost associated with the transaction.
| The price of shipping associated with the purchase in the given currency.
|-
|-
! shippingAddress
! shippingAddress
| address
| NO
| This structure represents a shipping address related to a payment. See below the address type for the appropriate structure and syntax.
| object
| The shipping address given in the format detailed below.
|-
|-
! paymentMethod
! tax
| text
| NO
| Payment method of the purchase. E.g. Barion, PayPal, CashOnDelivery, Klarna
|-
! option
| text
| Additional field that can describe option information on the checkout page (e.g. delivery method)
|-
! customerValue
| float
| float
| The value of a user performing this event to the business.
| The tax associated with the purchase in the given currency.
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Initiate purchase event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items </strong>
|-
|-
! searchString
|  // sample product data
| text
        var initiatePurchaseProperties = {
| In case of Search event. The string entered by the user for the search.
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
            'list': 'Checkout',
            'opt': 'To postal office, no street address',
            'orderNumber': '852',
            'positioning': '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',
                'zipCode': '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);
        });
 
|}
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For ticket sellers </strong>
|-
|-
! totalResults
|    // sample product data
| number
        var initiateCheckoutProperties = {
| Results found in case of a search
            'contents': [{
                'contentType': 'Product',
                'currency': 'GBP',
                'id': 'metalica_12',
                'name': 'Metallica',
                'quantity': 2.0,
                'totalItemPrice': 600.0,
                'unit': 'pcs',
                'unitPrice': 300.0,
                'category': 'Pop|Metal',
                'description': 'Early Bird',
                'ean': '9780575115347',
                'imageUrl': 'https://www.revolvermag.com/sites/default/files/styles/image_954_x_537/public/media/images/article/metallicapr.jpg',
                'variant': '2019.06.08 20:00|Slane Castle'
                },
                {
                'contentType': 'Product',
                'currency': 'GBP',
                'id': 'snoop_dog_2019',
                'name': "Snoop Dog",
                'quantity': 3.0,
                'totalItemPrice': 1500.0,
                'unit': 'pcs',
                'unitPrice': 500,
                'category': 'Rap',
                'description': 'Early Bird',
                'ean': '9780575115347',
                'imageUrl': 'https://cdn1.thr.com/sites/default/files/2012/08/snoop-dogg-pr-08-p.jpg',
                'variant': '2019.04.02 23:00|Wembley'
                }],
            'currency': 'GBP',
            'revenue': 2100.0,
            'step': 6,
            'contentType': 'Product',
            'coupon': '43763436874',
            'creative': 'preselected_cart_01',
            'customerValue': 150.0,
            'list': 'Checkout',
            'opt': 'To postal office, no street address',
            'orderNumber': '852',
            'positioning': '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',
                'zipCode': '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);
        });
 
|}
|}


=== User Properties ===
== Set User Properties (setUserProperties) ==


For the '''setUserProperties''' event there are a custom set of properties that may be set when used.
* Firing event: ''Button click'' when user properties are available
* User intent: Provide personal details
* Why do we need this: Information about users helps us give more relevant offers to them


This event should be attached to any browser event that when fired, can access user information. We handle all user
information in accordance with the GDPR and as such, all personally identifying information is hashed directly on the
client side, in the JS code, before being forwarded to us, which makes it impossible to read it on our side. This makes
it very important to fill out the properties provided below correctly, so that all PII falls in the correct fields that
will be hashed before sending. The pages that this event can be inserted into are mostly sign up or sign in pages,
newsletter subscription pages, and any other page where the user can provide information about themselves. This event
can also be sent during the checkout process.


'''Table 3: setUserProperties properties'''
 
 
'''Set user properties event properties'''


{| class="wikitable"
{| class="wikitable"
! Key
! key
! Value Type
! required
! Description
! hashed
! Required
! type
! description
|-
|-
! userId
! userId
| YES
| YES
| text
| text
| User Id
| Your ID for the user, for example an username, email or internal ID that you identify the user with on your site.
| YES
|-
|-
! email
! accountCreatedTime
| text
| NO
| Email address. '''Hashed automatically for privacy purposes.'''
| NO
| NO
| UNIX timestamp
| The time that the user account had been created, in a UNIX timestamp that is seconds accurate.
|-
|-
! phone
! age
| NO
| NO
| text
| text
| Phone number ina format of IPF ()International Phone Number) eg. +1-541-754-3010. '''Hashed automatically for privacy purposes.'''
| The age of the user.
|-
! city
| NO
| NO
|-
! accountCreatedTime
| UNIX timestamp
| When the user account was created
| NO
| NO
| text
| The city that the user lives in.
|-
|-
! country
! country
| NO
| NO
| text
| text
| The country in which the user lives. ISO 3166-1 alpha-2 codes are preferred.
| The country that the user lives in, preferably in the ISO 3166-1 alpha-2 format, eg. HU or CZ.
|-
! region
| NO
| NO
| NO
| text
| The region that the user lives in, preferably in the ISO 3166-2 format, eg. HU-BU.
|-
|-
! county
! currency
| NO
| NO
| text
| text
| The county in which the user lives
| Currency that the user prefers, or the one that the prices are displayed to them in. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
| NO
|-
|-
! city
! email
| text
| The city in which the user lives
| NO
| NO
|-
| YES
! zipCode
| text
| text
| The zip code of the user
| The email that belongs to the user.
| NO
|-
|-
! gender
! gender
| NO
| NO
| text
| text
| The gender of the user. Possible values: M - Male, F - Female
| The gender of the user.
|-
! interests
| NO
| NO
| NO
| text
| | The interests of the user, separated with the pipe character, eg. "Arts|Games".
|-
|-
! age
! lang
| integer
| NO
| Age of user
| NO
| NO
| text
| The language of the user, preferably in the ISO 639-1 format, eg. hu or cz.
|-
|-
! currency
! phone
| text (ISO 4217 format)
| The preferred currency of the user. 3 digit currency code required.
| NO
| NO
| YES
| text
| Phone number of the user, preferably in the E.164 format, eg. +36 1 111 1111
|-
|-
! language
! shippingAddress
| 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
| NO
| object
| The address of the user in the format described below.
|-
|-
! step
! step
| integer
| A number represents a step in the checkout process. Optional on checkout actions.
| NO
| NO
| NO
| text
| If the user properties are set in the checkout process, the checkout process step.
|-
|-
! sessionId
! zipCode
| NO
| NO
| text
| text
| Session Id
| The ZIP code
| NO
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Set user properties event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> General example </strong>
|-
|  // sample user data
        var setUserPropertiesProperties= {
            'userId': 'user_42',
            'accountCreatedTime': 1557223622,
            'age': '12-24',
            'city': 'Budapest',
            'country': 'HU',
            'region': 'HU-BU',
            'currency': 'HUF',
            'email': '[email protected]',
            'gender': 'male',
            'interests': 'Arts|Crafts',
            'lang': 'hu',
            'phone': '+36 1 111 1111',
            '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',
                'zipCode': '1111'
            },
            'step': 1,
            'zipCode': '1111'
        }
 
 
        // 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('next').addEventListener('click', function() {
            bp('track', 'setUserProperties', setUserPropertiesProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#next").click(function() {
            bp('track', 'setUserProperties', setUserPropertiesProperties);
        });
 
|}
|}


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


== Category Selection (categorySelection) ==


'''Table 4: The contents type properties'''
* Firing event: ''Button click'' on a category on a category selection page
* User intent: View a category
* Why do we need this: Users demonstrate interest in items belonging to a category by looking at the category
 
This event should be implemented where the user can select a category of events on a page, for example a brand, a common
property, a theme, a price range or any grouping of product along something that makes them belong to the category.
 
 
 
'''Category selection event properties'''


{| class="wikitable"
{| class="wikitable"
! Property name
! key
! Property type
! required
! Description
! type
! Required
! description
|-
|-
! id
! id
| text
| SKU of product/id of article/the promotion ID/etc.
| YES
| YES
|-
! contentType
| text
| text
| Possible values: Product/Article/Promotion/Banner/Misc
| Unique ID of the category clicked on your site.
| YES
|-
|-
! name
! name
| YES
| text
| text
| Full Name of product/article/promotion etc (e.g. Android T-Shirt or e.g. Summer Sale)
| Full name of the category. (eg. 'shoes')
| YES
|-
|-
! brand
! brand
| NO
| text
| text
| Brand part of product/brand described in article
| Brand of the item in the category clicked.
| YES
|-
|-
! category
! category
| NO
| text
| | The category (eg. 'winter shoes' or 'summer shoes') or subcategory branch (eg. 'clothes|winter|shoes' or 'clothes|summer|shoes', separate levels with '|') of the category that was clicked.
|-
! [[#Special_properties|contents]]
| NO
| array
| An array of JS objects for detailing items in the category. For more details see the table below.
|-
! 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
|-
! customerValue
| NO
| float
| The value of a user performing this event to the business.
|-
! list
| NO
| text
| The collection that the category clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
|-
|-
! unit
! positioning
| NO
| text
| text
| The measurement unit of the item.
| The category'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.
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Category selection event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items </strong>
|-
|  // sample category data
        var categorySelectionProperties = {
            'id': 'books_scifi',
            'name': 'Sci-Fi Books',
            'category': 'Books',
            'contentType': 'Page',
            'customerValue': 150.0,
            'list': 'SearchPage',
            'positioning': '42'
        }
 
        // 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('select_category').addEventListener('click', function() {
            bp('track', 'categorySelection', categorySelectionProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#select_category").click(function() {
            bp('track', 'categorySelection', categorySelectionProperties);
        });
 
|}
 
 
 
== Click Product (clickProduct) ==
 
* Firing event: ''Button click'' on an item
* User intent: View an item
* Why do we need this: Users demonstrate interest in your items by clicking them
 
This event should be fired each time when a user selects any of your items and then the item's page will be loaded. 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"
! key
! required
! type
! description
|-
! 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.
|-
|-
! unitPrice
! currency
| float
| Price of product (the price of one measurement unit of the item).
| YES
| YES
| text (ISO 4217)
| Currency that the item is listed in for purchase. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
|-
|-
! totalItemPrice
! id
| float
| The total price of the item.
| YES
| YES
| text
| Unique ID of the item clicked on your site.
|-
|-
! currency
! name
| text (ISO 4217 format)
| Currency of product
| YES
| YES
| text
| Full name of the item clicked.
|-
|-
! quantity
! quantity
| integer
| The quantity of a product (e.g. 2)
| YES
| YES
| float
| The quantity of a product clicked measured in the unit provided (e.g. 2).
|-
|-
! variant
! unit
| YES
| text
| text
| The variant of the product (e.g. Black)
| 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
| NO
| text
| Brand of the item clicked.
|-
|-
! description
! category
| NO
| text
| text
| The detailed description of the item.
| 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.
|-
! [[#Special_properties|contents]]
| NO
| NO
| array
| An array of JS objects for detailing multiple items clicked. For more details see the table below.
|-
|-
! imageUrl
! creative
| NO
| text
| text
| A URL pointing to an image that shows the item.
| 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
| NO
| float
| The value of a user performing this event to the business.
|-
|-
! ean
! ean
| NO
| text
| text
| Contains the International Article Number (EAN) when applicable.
| Contains the International Article Number (EAN) of the item if available.
|-
! list
| NO
| NO
| text
| The collection that the product clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
|-
! positioning
| 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 when item is clicked through checkout.
|-
! variant
| NO
| text
| The variant of the product (e.g. 'black<nowiki>|</nowiki>XS') clicked.
|}
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
''' Click product event implementation examples: '''
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items in checkout process </strong>
|-
|  // 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.0,
            'unit': 'pcs',
            'unitPrice': 2500.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'creative': 'book_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'Checkout',
            'positioning': '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.0,
            '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.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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',
            'positioning': '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);
        });


'''Figure 7'''
|}


<nowiki>
== Click Product Detail (clickProductDetail) ==
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 );
* Firing event: ''Button click'' requesting extended details about an item
</nowiki>
* User intent: View extended information about an item
* Why do we need this: Users demonstrate high interest in your items by looking up details about them


=== Address value type ===
This event should fire on a button click that can be either a webpage or an asynchronous request for more details about
an item. It should be implemented at any button that results in more details being shown about an item.


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




'''Table 5: The address value type properties'''
'''Click product detail event properties'''


{| class="wikitable"
{| class="wikitable"
! Property name
! key
! Property type
! required
! Description
! type
! Required
! 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.
|-
|-
! deliveryMethod
! name
| YES
| text
| text
| The delivery method, if applicable.
| Full name of the item clicked.
| No
|-
|-
! country
! unit
| YES
| text
| text
| The recipient's country code in ISO-3166-1 alpha-2 format.
| The measurement unit of the item clicked. (e.g. pcs, kg).
| No
|-
! unitPrice
| YES
| float
| Price of one unit (that you provided) of the item clicked (in the currency that you provided).
|-
|-
! city
! brand
| NO
| text
| text
| The complete name of the city of the recipient address.
| Brand of the item clicked.
| No
|-
|-
! region
! category
| NO
| text
| text
| The region code of the recipient address in ISO-3166-2 format
| 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.
| No
|-
! [[#Special_properties|contents]]
| NO
| array
| An array of JS objects for detailing multiple items clicked. For more details see the table below.
|-
|-
! zip
! creative
| NO
| text
| text
| The zip code of the recipient address.
| 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.
| No
|-
! customerValue
| NO
| float
| The value of a user performing this event to the business.
|-
|-
! street
! ean
| NO
| text
| text
| The shipping street address with house number and other details.
| Contains the International Article Number (EAN) of the item if available.
| No
|-
|-
! street2
! list
| NO
| text
| text
| The address, continued.
| The collection that the product clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
| No
|-
|-
! fullName
! positioning
| NO
| text
| text
| The full civil or official name of the recipient.
| The product's position in the list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
| No
|-
! step
| NO
| integer
| A number that represents the progress in the checkout process.
|-
! quantity
| NO
| float
| The quantity of a product clicked measured in the unit provided (e.g. 2).
|-
|-
! phone
! variant
| NO
| text
| text
| The phone number of the recipient.
| The variant of the product (e.g. 'black<nowiki>|</nowiki>XS') clicked.
| No
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Click product detail event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items in checkout process</strong>
|-
|-
|  // sample product data for single product
        var clickProductDetailProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'unit': 'pcs',
            'unitPrice': 2500.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'creative': 'book_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'Checkout',
            'positioning': '1',
            'step': 2,
            'quantity': 1.0,
            'variant': 'hardcover'
        }
        // sample product data for bundle offer
        var clickProductDetailProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42pack',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            '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.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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',
            'positioning': '1',
            'step': 2,
            'quantity': 1.0,
            '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('more_details').addEventListener('click', function() {
            bp('track', 'clickProductDetail', clickProductDetailProperties);
        });
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#more_details").click(function() {
            bp('track', 'clickProductDetail', clickProductDetailProperties);
        });
|}
|}


'''Figure 8'''
== Customize Product (customizeProduct) ==


<nowiki>
* Firing event: ''Button click'' changing particular characteristics of an item
'shippingAddress': {
* User intent: Change characteristics of an item
          'deliveryMethod': 'ship',
* Why do we need this: Users demonstrate interest in your items by customizing them
          '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 ==
This event should fire on a button click that can be either a webpage or an asynchronous request for a different variant
of an item. It should be implemented at any button that allow customers to suit items for their needs before adding to cart, e.g. in colour or size.


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




'''Table 6: Properties of events related to content browsing'''
'''Customize product event properties'''


{| class="wikitable"
{| class="wikitable"
!
! key
!colspan = "5"| Event
! required
|-
! type
! Property
! description
! contentView
! clickProduct
! clickProductDetail
! customizeProduct
! clickPromo
|-
|-
! 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
| YES
| YES
| YES
| text (ISO 4217)
| YES
| Currency that the item is listed in for purchase. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
| YES
|-
|-
! id
! id
| YES
| YES
| YES
| text
| YES
| Unique ID of the item clicked on your site.
| YES
| YES
|-
|-
! name
! name
| YES
| YES
| text
| Full name of the item clicked.
|-
! unit
| YES
| YES
| YES
| text
| YES
| The measurement unit of the item clicked. (e.g. pcs, kg).
| YES
|-
|-
! unitPrice
! unitPrice
| YES*
| YES
| YES
| float
| Price of one unit (that you provided) of the item clicked (in the currency that you provided).
|-
! variant
| YES
| YES
| YES
| text
|
| The variant of the product (e.g. 'black<nowiki>|</nowiki>XS') clicked.
|-
! brand
| NO
| text
| Brand of the item clicked.
|-
! 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.
|-
! [[#Special_properties|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
|-
! positioning
| 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)
|-
! quantity
| NO
| float
| The quantity of a product clicked measured in the unit provided (e.g. 2).
|-
! step
| NO
| integer
| A number that represents the progress in the checkout process.
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Customize product event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items in checkout process </strong>
|-
|  // sample product data for single product
        var customizeProductProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'unit': 'pcs',
            'unitPrice': 2500.0,
            'variant': 'hardcover',
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'creative': 'book_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'Checkout',
            'positioning': '1',
            'step': 2,
            'quantity': 1.0,
        }
 
 
        // sample product data for bundle offer
        var customizeProductProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42pack',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'unit': 'pcs',
            'unitPrice': 15000.0,
            'variant': 'hardcover',
            '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.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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',
            'positioning': '1',
            'step': 2,
            'quantity': 1.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('customize').addEventListener('click', function() {
            bp('track', 'customizeProduct', customizeProductProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#customize").click(function() {
            bp('track', 'customizeProduct', customizeProductProperties);
        });
 
|}
 
== Purchase (purchase) ==
 
* Firing event: ''Page load'' after the payment process
* User intent: Verify the completion of the transaction
* 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. Avoiding irrelevant ads
 
This event should be fired on the page load where the user is notified about the completion of their transaction that is finished by successful payment. If the user chooses cash as the method of payment, usually this event should be fired when the ‘thank you’ page is loaded, if they choose online payment it should be fired when the ‘successful payment’ page is loaded. If the payment wasn't successful, then still this event still needs to be fired, except the 'step' property should set to a '-1' value.
 
 
 
'''Purchase event properties'''
{| class="wikitable"
! key
! required
! type
! description
|-
|-
! unit
! [[#Special_properties|contents]]
| YES*
| YES
| YES
| YES
| array
| YES
| 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
! currency
| YES*
| YES
| 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
| 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
| YES
|
| integer
| In most cases, since this is after the last checkout step, this should be the maximum value that you use. If the transaction is unsuccessful, this should be -1.
|-
|-
! quantity
! contentType
| YES*
| NO
| YES
| text
|
| Usually this value should be "Product".
|
|
|-
|-
! variant
! coupon
|
| NO
|
| text
|
| The coupon code that is being used.
| 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
! opt
|
| NO
|
| text
|
| Additional information about the purchase.
|
|
|-
|-
! category
! orderNumber
|
| NO
|
| text
|
| The unique ID of the purchase.
|
|
|-
|-
! list
! positioning
|
| 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).
|
|
|-
|-
! position
! shipping
|
| NO
|
| float
|
| The price of shipping associated with the purchase in the given currency.
|
|
|-
|-
! step
! shippingAddress
|
| NO
|
| object
|
| The shipping address given in the format detailed below.
|
|
|-
|-
! customerValue
! tax
|
| NO
|
| float
|
| The tax associated with the purchase in the given currency.
|
|}
|
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Purchase event implementation example: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> Successful purchase example for physical items </strong>
|-
|-
!
|       var purchaseProperties = {
|colspan = "5"| * Required only in case of contentType=Product when using the contentView event.
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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': 7,
            'contentType': 'Product',
            'coupon': '43763436874',
            'creative': 'preselected_cart_01',
            'customerValue': 150.0,
            'list': 'Checkout',
            'opt': 'To postal office, no street address',
            'orderNumber': '852',
            'positioning': '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',
                'zipCode': '1111'
            },
            'tax': 0.0
        }
 
        bp('track', 'purchase', purchaseProperties);
 
|}
|}


== Purchase related events ==
== Remove from Cart (removeFromCart) ==


These events refer to purchase intentions and effective checkouts and purchases. These events also share a number of common properties.
* Firing event: ''Button click'' that results in a product to be removed from the items selected for purchase
* User intent: Deselect product for purchase
* Why do we need this: Users demonstrate interest in carted products, and this can be refined if we know when products are deselected


=== addToCart/removeFromCart ===
The remove from cart event is very similar to the add to cart event, and is mainly required to refine our data on
selected items by informing us when products are taken out from the cart or deselected from purchase. It can also mean
that a purchase process that first made a user select an item is simply cancelled.


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




'''Table 7: addToCart/removeFromCart event properties'''
'''Remove from cart event properties'''
 
{| class="wikitable"
{| class="wikitable"
! Property
! key
! Required
! required
! type
! description
|-
|-
! contentType
! contentType
| YES
| YES
| text
| Usually, this value should be "Product".
|-
|-
! currency
! currency
| YES
| YES
| text (ISO 4217)
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
|-
|-
! id
! id
| YES
| 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
! name
| YES
| YES
| text
| The full name that you have for the added item, for example a product name (eg. Red Bull 24pcs carton).
|-
|-
! quantity
! quantity
| YES
| YES
| float
| The quantity of the item removed from the cart.
|-
|-
! totalItemPrice
! totalItemPrice
| YES
| YES
| float
| The total price of the removed items in the given currency.
|-
|-
! unit
! unit
| YES
| YES
| text
| The unit that your item is measured in (eg. pieces, kg, hours).
|-
|-
! unitPrice
! unitPrice
| YES
| YES
| float
| The price of one measurement of your item in the given currency.
|-
|-
! brand
! brand
|
| NO
| text
| The brand of the item.
|-
|-
! category
! 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.
|-
|-
! contents
! [[#Special_properties|contents]]
|
| NO
| array
| An array of JS objects for detailing multiple items of the item. For more details see the table below.
|-
|-
! coupon
! coupon
|
| NO
| text
| The coupon code that was used when the item was removed from cart.
|-
|-
! creative
! creative
|
| NO
| text
| Seldom used, for example a promotion that changes a product in your cart to a better, more expensive or more recent one.
|-
|-
! customerValue
! customerValue
|
| NO
| float
| A metric that you define that measures the value of the action performed to your business.
|-
|-
! ean
! ean
|
| NO
| text
| Contains the International Article Number (EAN) of the item if available.
|-
|-
! list
! list
|
| NO
| text
| The function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
|-
|-
! position
! positioning
|
| 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
! step
|
| NO
| integer
| If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 1 as the checkout initiation.
|-
|-
! variant
! 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)
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Remove from cart event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items in basket page </strong>
|-
|  // sample product data for single items
        var removeFromCartProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': 10.0,
            'totalItemPrice': 49900.0,
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'coupon': '43763436874',
            'creative': 'upsell_promo_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'BasketPage',
            'positioning': '3',
            'variant': 'hardcover'
        }
 
        // sample product data for bundled items
        var removeFromCartProperties = {
            'contentType': 'Product',
            'currency': 'HUF',
            'id': 'item_42pack',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'quantity': 10.0,
            'totalItemPrice': 150000.0,
            '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.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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'
                }],
            'coupon': '43763436874',
            'creative': 'upsell_promo_42',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'BasketPage',
            'positioning': '3',
            '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('remove_button').addEventListener('click', function() {
            bp('track', 'removeFromCart', removeFromCartProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#remove_button").click(function() {
            bp('track', 'removeFromCart', removeFromCartProperties);
        });
 
|}
|}


=== initiateCheckout, addPaymentInfo, initiatePurchase, purchase ===


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


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.
* Firing event: ''Button click'' at a point in the checkout process where the payment method is already set
* User intent: Select payment method
* Why do we need this: It helps to identify user financial habits


This event should be fired when the payment method of a user is already entered. This event should be fired both if
the payment info is explicitly requested and provided, but also if it is only implied for example when only one option
is available.


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


'''Add payment info event properties'''
{| class="wikitable"
{| class="wikitable"
!
! key
!colspan="4"|event
! required
|-
! type
! Property
! description
! initiateCheckout
! addPaymentInfo
! initiatePurchase
! purchase
|-
! contents
| YES
| YES
| YES
| YES
|-
|-
! step
! [[#Special_properties|contents]]
| 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.
|-
|-
! paymentMethod
! paymentMethod
| UNAVAILABLE
| YES
| YES
| UNAVAILABLE
| text
| UNAVAILABLE
| The method of payment that the user chooses, for example Barion, cash etc.
|-
|-
! revenue
! step
|
| YES
| YES
| YES
| YES
|-
| integer
! currency
| It representing the current number of step in the checkout process.
|
|
|
|
|-
|-
! contentType
! contentType
|
| NO
|
| text
|
| Usually this value should be "Product".
|
|-
|-
! coupon
! coupon
|
| NO
|
| text
|
| The coupon code that is being used.
|
|-
|-
! 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.
|
|-
! currency
| NO
| text (ISO 4217)
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
|-
|-
! customerValue
! customerValue
|
| NO
|
| float
|
| A metric that you define that measures the value of the action performed to your business.
|
|-
|-
! list
! list
|
| NO
|
| text
|
| In most cases this should be 'Checkout'.
|
|-
|-
! option
! opt
|
| NO
|
| text
|
| Additional information about the purchase.
|
|-
|-
! orderNumber
! orderNumber
|
| NO
|
| text
|
| The unique ID of the purchase.
|
|-
|-
! position
! positioning
|
| 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).
|
|-
! 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.
|-
|-
! shipping
! shipping
|
| NO
|
| float
|
| The price of shipping associated with the purchase in the given currency.
|
|-
|-
! shippingAddress
! shippingAddress
|
| NO
|
| object
|
| The shipping address given in the format detailed below.
|
|-
|-
! tax
! tax
|
| NO
|
| float
|
| The tax associated with the purchase in the given currency.
|
|}
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
''' Add payment info event implementation examples: '''
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For physical items </strong>
|-
|  // sample product data
        var addPaymentInfoProperties = {
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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'
                }],
            'paymentMethod': 'Barion',
            'step': 1,
            'contentType': 'Product',
            'coupon': '43763436874',
            'creative': 'preselected_cart_01',
            'currency': 'HUF',
            'customerValue': 150.0,
            'list': 'Checkout',
            'opt': 'To postal office, no street address',
            'orderNumber': '852',
            'positioning': '1',
            'revenue': 17500.0,
            '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',
                'zipCode': '1111'
            },
            'tax': 0.0
        }


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


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.
        // vanilla JS (if you don't use jQuery, if in your console "$" is not defined on your site)
        document.getElementById('checkout_next').addEventListener('click', function() {
            bp('track', 'addPaymentInfo', addPaymentInfoProperties);
        });


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


'''Table 9: Properties of search event'''
|}
 
== Click Promo (clickPromo) ==
 
* Firing event: ''Button click'' on a promotion box only on your site.
* User intent: View a promotion
* Why do we need this: Users demonstrate interest in your promotion offers by clicking them
 
This event should be fired when one of your users selects a promotion on your site. Promotions can be usually placed on home pages,
product places, in the checkout process and many other places. The promotion can be about a product, offer, brand or any
other single offer or grouping of offers. This event should be implemented only on promotions that you serve on your page natively,
as opposed to those served dynamically by external third party services such as Google Ads.
 
 
'''Click promo event properties'''


{| class="wikitable"
{| class="wikitable"
! Key
! key
! Required
! required
! type
! description
|-
|-
! searchString
! contentType
| YES
| YES
| text
| The type of the content of the page where the promotion was selected. Possible values (only these are accepted): Page/Product/Article/Promotion/Banner/Misc.
|-
|-
! contentType
! creative
|
| YES
| text
| The name or description of the promotion, for example a promotion picture filename or slogan of the promotion.
|-
|-
! id
! id
|
| YES
| text
| Unique ID of the promotion clicked on your site.
|-
|-
! name
! name
|
| YES
| text
| Full name of the promotion.
|-
! brand
| NO
| text
| Brand of the item in the promotion clicked.
|-
! 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 in the promotion clicked.
|-
|-
! contents
! [[#Special_properties|contents]]
|
| NO
| array
| An array of JS objects for detailing multiple items promoted. For more details see the table below.
|-
|-
! totalResults
! currency
|
| NO
| text (ISO 4217)
| Currency that the promoted offer is listed in. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
|-
|-
! customerValue
! 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 promotion clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
|-
! positioning
| NO
| text
| The promotion's position in the list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
|-
! quantity
| NO
| float
| The quantity that the item is promoted in, measured in the unit provided (e.g. 2).
|-
! step
| NO
| integer
| A number that represents the progress in the checkout process.
|-
! unit
| NO
| text
| The measurement unit of the item promoted (e.g. pcs, kg).
|-
! unitPrice
| NO
| float
| Price of one unit (that you provided) of the item promoted (in the currency that you provided).
|-
! variant
| NO
| text
| The variant of the product (e.g. 'black|XS') promoted.
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Click promo event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> In checkout process </strong>
|-
|-
! currency
|  // sample product data for single product
|
        var clickPromoProperties = {
            'contentType': 'Product',
            'creative': 'book_42',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'currency': 'HUF',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'Checkout',
            'positioning': '1',
            'quantity': 1.0,
            'step': 2,
            'unit': 'pcs',
            'unitPrice': 2500.0,
            'variant': 'hardcover'
        }
 
 
        // sample product data for bundle offer
        var clickPromoProperties = {
            'contentType': 'Product',
            'creative': 'bundle_offer_01',
            'id': 'item_42pack',
            'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
            '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.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'list': 'Checkout',
            'positioning': '1',
            'quantity': 1.0,
            'step': 2,
            'unit': 'pcs',
            'unitPrice': 15000.0,
            '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_promo').addEventListener('click', function() {
            bp('track', 'clickPromo', clickPromoProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#book_42_promo").click(function() {
            bp('track', 'clickPromo', clickPromoProperties);
        });
 
|}
|}


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


== Sign Up (signUp) ==


'''Table 10: Properties of signUp event'''
* Firing event: ''Button click'' that completes the registration or login process
* User intent: Register for or login to a user account or a newsletter subscription
* Why do we need this: Users demonstrate interest in your market area by signing up for an account


This event should be usually sent along the set user properties event in registration process, since this event only captures the actual signup,
not the user itself. This event should both be fired if a user registers for an account or subscription for the first
time and when they login afterwards. Unsuccessful login or signup events should cause error events to be sent. If
possible, it is better if only successful attempts send a sign up event, but it is more important for all signing ups to
send an event than for each signup to be only sent once.
'''Sign up event properties'''
{| class="wikitable"
{| class="wikitable"
! Key
! key
! Required
! required
! type
! description
|-
|-
! contentType
! contentType
| YES
| YES
| text
| If the user signs up for a product, then it should be 'Product' else this can be 'Page' if it is a general registration or login.
|-
|-
! id
! id
| YES
| YES
| text
| This should be your unique ID for the form used to register or login.
|-
|-
! name
! name
| YES
| YES
| text
| The name of the for used for the signing up, for example 'Register' or 'Sign In'.
|-
! brand
| NO
| text
| The brand of the product the user signs up for.
|-
|-
! contents
! 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.
|-
|-
! customerValue
! [[#Special_properties|contents]]
|
| NO
| array
| An array of JS objects for detailing multiple items of the item. For more details see the table below.
|-
|-
! currency
! currency
|
| NO
| text (ISO 4217)
| The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
|-
! customerValue
| NO
| float
| A metric that you define that measures the value of the action performed to your business.
|-
|-
! ean
! ean
|
| NO
| text
| Contains the International Article Number (EAN) of the offer if available.
|-
|-
! brand
! unit
|
| NO
| text
| The unit that your subscribed item is measured in (eg. pieces, kg, hours).
|-
|-
! category
! unitPrice
|
| NO
| float
| The price of one measurement of your item in the given currency.
|-
|-
! variant
! variant
|
| NO
| text
| THehvariant 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)
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Sign up event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> Newsletter for a given item</strong>
|-
|-
! unit
|  // sample subscription data
|
        var signUpProperties = {
            'contentType': 'Product',
            'id': 'item_42',
            'name': "Hitchhikers' Guide to the Galaxy, newsletter",
            'brand': 'Gollancz',
            'category': 'books|hardcover|scifi, books|hardcover|comedy',
            'currency': 'HUF',
            'customerValue': 150.0,
            'ean': '9780575115347',
            'unit': 'pcs.',
            'unitPrice': 4990.0,
            '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('signup_button').addEventListener('click', function() {
            bp('track', 'signUp', signUpProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#signup_button").click(function() {
            bp('track', 'signUp', signUpProperties);
        });
 
|}
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> Registration </strong>
|-
|  // sample subscription data
        var signUpProperties = {
            'contentType': 'Page',
            'id': 'registration_form_1',
            'name': 'Registration'
        }
 
 
        // 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('signup_button').addEventListener('click', function() {
            bp('track', 'signUp', signUpProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#signup_button").click(function() {
            bp('track', 'signUp', signUpProperties);
        });
 
|}
 
 
 
== Search (search) ==
 
* Firing event: ''Button click'' that starts a search on a page
* User intent: Search for an offer on your page
* Why do we need this: Users demonstrate interest in an offer by searching for it
 
This event is quite straightforward, every time a search button is clicked, this should send. If the search has no
search button, but instead gives results on the change of the search box, then this event can be sent if the user clicks
on a result. In this case, searches are sent asynchronously for partial search terms, which should not in themselves
send an event. If you have a product selection page where items can be filtered, then the same can apply, the search
string in this case can be the query that the settings make that can be read in your browser address bar in HTTP
properties (eg. 'goats' in this: 'https://www.google.com/search?ei=A3rRXNHmJY-nrgSJs5HgDQ&q=goats').
 
 
 
'''Search event properties'''
{| class="wikitable"
! key
! required
! type
! description
|-
! searchString
| YES
| text
| The search terms entered by the user or the HTTP property that contains the search terms.
|-
! [[#Special_properties|contents]]
| NO
| array
| An array of JS objects containing the top ten results of your search.
|-
! contentType
| NO
| text
| Usually this should be 'Product'.
|-
! currency
| NO
| text (ISO 4217)
| If you have a filter that selects products by price, and the search string doesn't contain this, then you should provide it here.
|-
! customerValue
| NO
| float
| A metric that you define that measures the value of the action performed to your business.
|-
! id
| NO
| float
| The id of the search facility that the search is made in, for example of a search box or a filter array.
|-
! name
| NO
| text
| The name of the search facility that the search is made in, for example of a search box or a filter array.
|-
|-
! unitPrice
! totalResults
|
| NO
| integer
| The number of the search or filter results.
|}
<span style="font-size:80%; line-height: 1.31em;">(*It's possible to add [[#Special_properties|custom property]])</span>
 
 
''' Search event implementation examples: '''
 
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> General example</strong>
|-
|-
! totalItemPrice
|  // sample search result data
|
        var searchProperties = {
            'searchString': 'big GOATS',
            'contents': [{
                'contentType': 'Product',
                'currency': 'HUF',
                'id': 'item_42',
                'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                'quantity': 3.0,
                'totalItemPrice': 7500.0,
                'unit': 'pcs',
                'unitPrice': 2500.0,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                'totalItemPrice': 25935,
                'unit': 'pcs',
                'unitPrice': 8645,
                'brand': 'Gollancz',
                'category': 'books|hardcover|scifi, books|hardcover|comedy',
                'description': 'The Hitchhikers Guide to the Galaxy 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',
            'customerValue': 150.0,
            'id': 'search_01',
            'name': 'Book Search',
            'totalResults': 2
        }
 
 
        // 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('search_button').addEventListener('click', function() {
            bp('track', 'search', searchProperties);
        });
 
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#search_button").click(function() {
            bp('track', 'search', searchProperties);
        });
 
|}
|}


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


== Error (error) ==


'''Table 11: Properties of error event'''
* Firing event: Any event that results in erroneous operation
* User intent: Something else
* Why do we need this: We can get more information about event failures


This event should be sent each time the page can't complete the requested operation, for examnple on 40x or 50x pages,
failed form submissions et cetera.
'''Error event properties'''
{| class="wikitable"
{| class="wikitable"
! Key
! key
! Required
! required
! type
! description
|-
! description
| YES
| text
| The description of the error, or preferably the full error message.
|-
|-
! code
! code
| NO
| int
| The error code.
|}
''' Error event implementation examples: '''
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For 404 error </strong>
|-
|  // on a static 404 page
        var errorProperties = {
            'description': 'I find your lack of navigation disturbing.',
            'code': 404
        }
        bp('track', 'error', errorProperties);
|}
== Custom Event (customEvent) ==
* Firing event: Any action that can't be described with our events
* User intent: Something different
* Why do we need this: We can get more information
This event is for describing any event that can't be otherwise described with our standard events.
'''Custom event properties'''
{| class="wikitable"
! key
! required
! type
! description
|-
! _eventAction
| NO
| text
| The action that the user takes, eg. click.
|-
! _eventCategory
| NO
| text
| The category that the event falls in, you can define it for yourself, eg. 'user_settings'.
|-
! _eventLabel
| NO
| text
| The label associated with the event, eg. 'language_selection'.
|-
! _eventProperty
| NO
| text
| The property associated with the event, eg. 'unit_format'.
|-
! _eventValue
| NO
| text
| The value of the property associated with the event, eg. 'Inch'.
|}
''' Custom event implementation examples: '''
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> For measuring unit selection </strong>
|-
|      // for measuring unit selection
        var customEventProperties = {
            '_eventAction': 'click',
            '_eventCategory': 'user_settings',
            '_eventLabel': 'language_selection',
            '_eventProperty': 'unit_format',
            '_eventValue': 'Inch'
        }
        // 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('set_language').addEventListener('click', function() {
            bp('track', 'customEvent', customEventProperties);
        });
        // jQuery (if you use jQuery, if in your console "$" is defined on your site)
        $("#set_language").click(function() {
            bp('track', 'customEvent', customEventProperties);
        });
|}
= Special properties =
''' Contents value type - array of objects '''
{| class="wikitable"
! key
! 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
| 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 or SKU.
|-
! name
| YES
| YES
| text
| The full name that you have for the offer, for example a product name (eg. Red Bull 24pcs carton).
|-
! quantity
| YES
| float
| The quantity of the product offered as initially given on the page.
|-
! totalItemPrice
| YES
| float
| The total price of the added items in the given currency.
|-
! unit
| YES
| text
| The unit that your offer is measured in (eg. pieces, kg, m).
|-
! unitPrice
| YES
| 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.
|-
|-
! description
! description
| YES
| NO
| text
| The detailed description of item.
|-
! ean
| NO
| text
| Contains the International Article Number (EAN) of the offer if available.
|-
! imageUrl
| NO
| text
| The URL of the image of the viewed item.
|-
! 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)
|}
 
 
''' Address value type - array of objects '''
 
{| class="wikitable"
! key
! required
! type
! description
|-
! city
| NO
| text
| The complete name of the city of the recipient address.
|-
! country
| NO
| text (ISO-3166-1 alpha-2)
| The recipient's country code in ISO-3166-1 alpha-2 format.
|-
! deliveryMethod
| NO
| text
| The delivery method, if applicable.
|-
! fullName
| NO
| text
| The full civil or official name of the recipient.
|-
! phone
| NO
| text
| The phone number of the recipient.
|-
! region
| NO
| text (ISO-3166-2)
| The region code of the recipient address in ISO-3166-2 format.
|-
! street
| NO
| text
| The shipping street address with house number and other details.
|-
! street2
| NO
| text
| The address, continued.
|-
! zipCode
| NO
| text
| The zip code of the recipient address.
|}
 
 
''' Custom Property '''
 
{| class="wikitable"
! name
! Value Type
! Description
|-
| _custom
| any type
| If our predefined events and/or object properties don't suit your needs, you can include your own, custom events and/or properties. Custom properties can be used with standard events. Custom properties must start with an underscore.
|}
|}


'''Figure 9'''
''' Custom property implementation examples: '''


<nowiki>
{| role="presentation" class="wikitable mw-collapsible mw-collapsed"
| <strong> In purchase event </strong>
|-
|      //_custome_event_test
        var purchaseProperties = {
                'contents': [{
                    'contentType': 'Product',
                    'currency': 'HUF',
                    'id': 'item_42',
                    'name': "Hitchhikers' Guide to the Galaxy, hardcover, ISBN: 9780575115347",
                    'quantity': 3.0,
                    'totalItemPrice': 7500.0,
                    'unit': 'pcs',
                    'unitPrice': 2500.0,
                    'brand': 'Gollancz',
                    'category': 'books|hardcover|scifi, books|hardcover|comedy',
                    'description': 'The Hitchhikers Guide to the Galaxy 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.0,
                    'totalItemPrice': 25935,
                    'unit': 'pcs',
                    'unitPrice': 8645,
                    'brand': 'Gollancz',
                    'category': 'books|hardcover|scifi, books|hardcover|comedy',
                    'description': 'The Hitchhikers Guide to the Galaxy 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': 7,
                'contentType': 'Product',
                'coupon': '43763436874',
                'creative': 'preselected_cart_01',
                'customerValue': 150.0,
                'list': 'Checkout',
                'opt': 'To postal office, no street address',
                'orderNumber': '852',
                'positioning': '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',
                    'zipCode': '1111'
                },
                'tax': 0.0,
                '_myCustomProperty' : 'This is my first custom property'
            }


var errorData = {
            bp('track', 'purchase', purchaseProperties);
        'description': 'testError',
        'code': 485,
    }


    bp('track', 'error', errorData);
|}
</nowiki>

Latest revision as of 10:32, 6 March 2024

Barion Pixel API reference

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. Usage of a fully compliant consent management platform (CMP) is strongly recommended by Barion. You can find our recommendation here


Consent event implementation example 

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

Encrypting personal data (setEncryptedEmail, setEncryptedPhone)

  • Firing event: On click or per pageview when email / phone number is globally or occasionally available for the given user.
  • User intent: User types in their email (or phone number) for any reason, such as signing in, within checkout when placing an order, signig up for newsletter, etc.
  • Why do we need this: More accurate data collection after third party cookie phase out in compliance with GDPR.

We do not collect unencrypted personally identifiable information (PII). All PII data is encrypted by the SHA-1 algorithm that hides the real, human readable email address and phone number. The encryption process will always happen on Barion side whenever an unencrypted email address (or phone number) is being sent but it is also possible to send a previously SHA-1 encrypted email address (or phone number). Sending an empty string, invalid email address (or phone number) or a not properly hashed value will result in an error message. Please send email with lowercase letter and the phone number as customer type in.


setEncryptedEmail / setEncryptedPhone implementation example 

   
        bp('identity','setEncryptedEmail', '[email protected]');
        bp('identity','setEncryptedPhone', '+36301234567');

OR 

   
        var hashedEmailAddress = sha1('[email protected]');
        bp('identity','setEncryptedEmail', hashedEmailAddress);

        var hashedPhone = sha1('+36301234567');
        bp('identity','setEncryptedPhone', hashedPhone);

Content View (contentView)

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


This event should be fired when one of your users visit a page that refers to one of your items that can be bought or users read other information about something that is not connected to an item directly (e.g.: news, description, articles, blog posts etc.). Except product page, in most cases the page title is adequate for name property.


Content view event properties

key 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) in product page, otherwise in most cases page title is adequate. Please note that item names should be consistent in all events.
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.
imageUrl NO text The URL of the image of the viewed item.
list NO text The function of the loaded page from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
positioning 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 1 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)

(*It's possible to add custom property)


Content view event implementation examples:

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

key 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 (e.g. SKU)
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.
contents NO array An array of JS objects for detailing multiple items of the item. For more details see the table below.
coupon NO text The coupon code that was used when the item was added to cart.
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
positioning NO text The item's position in a list or collection (e.g. 2).
step NO integer If the page is displayed along the checkout process, the checkout step number that the page is displayed in, numbered from 1 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)

(*It's possible to add custom property)


Add to cart event implementation examples:

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

key 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 is not include all costs the customer pays like shipping or any discount.
step YES integer In most cases, since this is the first checkout step, this should be 1.
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'.
opt NO text Additional information about the purchase.
orderNumber NO text The unique ID of the purchase.
positioning 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.

(*It's possible to add custom property)


Initiate checkout event implementation examples:

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

key 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, tax or any discount.
step YES integer It is its sequential number in checkout process.
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'.
opt NO text Additional information about the purchase.
orderNumber NO text The unique ID of the purchase.
positioning 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.

(*It's possible to add custom property)


Initiate purchase event implementation examples:

Set User Properties (setUserProperties)

  • Firing event: Button click when user properties are available
  • User intent: Provide personal details
  • Why do we need this: Information about users helps us give more relevant offers to them

This event should be attached to any browser event that when fired, can access user information. We handle all user information in accordance with the GDPR and as such, all personally identifying information is hashed directly on the client side, in the JS code, before being forwarded to us, which makes it impossible to read it on our side. This makes it very important to fill out the properties provided below correctly, so that all PII falls in the correct fields that will be hashed before sending. The pages that this event can be inserted into are mostly sign up or sign in pages, newsletter subscription pages, and any other page where the user can provide information about themselves. This event can also be sent during the checkout process.


Set user properties event properties

key required hashed type description
userId YES YES text Your ID for the user, for example an username, email or internal ID that you identify the user with on your site.
accountCreatedTime NO NO UNIX timestamp The time that the user account had been created, in a UNIX timestamp that is seconds accurate.
age NO NO text The age of the user.
city NO NO text The city that the user lives in.
country NO NO text The country that the user lives in, preferably in the ISO 3166-1 alpha-2 format, eg. HU or CZ.
region NO NO text The region that the user lives in, preferably in the ISO 3166-2 format, eg. HU-BU.
currency NO NO text Currency that the user prefers, or the one that the prices are displayed to them in. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
email NO YES text The email that belongs to the user.
gender NO NO text The gender of the user.
interests NO NO text The interests of the user, separated with the pipe character, eg. "Arts|Games".
lang NO NO text The language of the user, preferably in the ISO 639-1 format, eg. hu or cz.
phone NO YES text Phone number of the user, preferably in the E.164 format, eg. +36 1 111 1111
shippingAddress NO NO object The address of the user in the format described below.
step NO NO text If the user properties are set in the checkout process, the checkout process step.
zipCode NO NO text The ZIP code

(*It's possible to add custom property)


Set user properties event implementation examples:


Category Selection (categorySelection)

  • Firing event: Button click on a category on a category selection page
  • User intent: View a category
  • Why do we need this: Users demonstrate interest in items belonging to a category by looking at the category

This event should be implemented where the user can select a category of events on a page, for example a brand, a common property, a theme, a price range or any grouping of product along something that makes them belong to the category.


Category selection event properties

key required type description
id YES text Unique ID of the category clicked on your site.
name YES text Full name of the category. (eg. 'shoes')
brand NO text Brand of the item in the category clicked.
category NO text The category (eg. 'winter shoes' or 'summer shoes') or subcategory branch (eg. 'clothes|winter|shoes' or 'clothes|summer|shoes', separate levels with '|') of the category that was clicked.
contents NO array An array of JS objects for detailing items in the category. For more details see the table below.
contentType NO text Usually this value should be "Product".
customerValue NO float The value of a user performing this event to the business.
list NO text The collection that the category clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
positioning NO text The category'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.

(*It's possible to add custom property)


Category selection event implementation examples:


Click Product (clickProduct)

  • Firing event: Button click on an item
  • User intent: View an item
  • Why do we need this: Users demonstrate interest in your items by clicking them

This event should be fired each time when a user selects any of your items and then the item's page will be loaded. 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

key 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 float 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
positioning 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 when item is clicked through checkout.
variant NO text The variant of the product (e.g. 'black|XS') clicked.

(*It's possible to add custom property)


Click product event implementation examples:

Click Product Detail (clickProductDetail)

  • Firing event: Button click requesting extended details about an item
  • User intent: View extended information about an item
  • Why do we need this: Users demonstrate high interest in your items by looking up details about them

This event should fire on a button click that can be either a webpage or an asynchronous request for more details about an item. It should be implemented at any button that results in more details being shown about an item.


Click product detail event properties

key 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.
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
positioning 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.
quantity NO float The quantity of a product clicked measured in the unit provided (e.g. 2).
variant NO text The variant of the product (e.g. 'black|XS') clicked.

(*It's possible to add custom property)


Click product detail event implementation examples:

Customize Product (customizeProduct)

  • Firing event: Button click changing particular characteristics of an item
  • User intent: Change characteristics of an item
  • Why do we need this: Users demonstrate interest in your items by customizing them

This event should fire on a button click that can be either a webpage or an asynchronous request for a different variant of an item. It should be implemented at any button that allow customers to suit items for their needs before adding to cart, e.g. in colour or size.


Customize product event properties

key 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.
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).
variant YES text The variant of the product (e.g. 'black|XS') clicked.
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
positioning 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)
quantity NO float The quantity of a product clicked measured in the unit provided (e.g. 2).
step NO integer A number that represents the progress in the checkout process.

(*It's possible to add custom property)


Customize product event implementation examples:

Purchase (purchase)

  • Firing event: Page load after the payment process
  • User intent: Verify the completion of the transaction
  • 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. Avoiding irrelevant ads

This event should be fired on the page load where the user is notified about the completion of their transaction that is finished by successful payment. If the user chooses cash as the method of payment, usually this event should be fired when the ‘thank you’ page is loaded, if they choose online payment it should be fired when the ‘successful payment’ page is loaded. If the payment wasn't successful, then still this event still needs to be fired, except the 'step' property should set to a '-1' value.


Purchase event properties

key 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 after the last checkout step, this should be the maximum value that you use. If the transaction is unsuccessful, this should be -1.
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'.
opt NO text Additional information about the purchase.
orderNumber NO text The unique ID of the purchase.
positioning 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.

(*It's possible to add custom property)


Purchase event implementation example:

Remove from Cart (removeFromCart)

  • Firing event: Button click that results in a product to be removed from the items selected for purchase
  • User intent: Deselect product for purchase
  • Why do we need this: Users demonstrate interest in carted products, and this can be refined if we know when products are deselected

The remove from cart event is very similar to the add to cart event, and is mainly required to refine our data on selected items by informing us when products are taken out from the cart or deselected from purchase. It can also mean that a purchase process that first made a user select an item is simply cancelled.


Remove from cart event properties

key 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 removed from the cart.
totalItemPrice YES float The total price of the removed 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.
contents NO array An array of JS objects for detailing multiple items of the item. For more details see the table below.
coupon NO text The coupon code that was used when the item was removed from cart.
creative NO text Seldom used, for example a promotion that changes a product in your cart to a better, more expensive or more recent one.
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 item 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
positioning 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 1 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)

(*It's possible to add custom property)


Remove from cart event implementation examples:


Add Payment Info (addPaymentInfo)

  • Firing event: Button click at a point in the checkout process where the payment method is already set
  • User intent: Select payment method
  • Why do we need this: It helps to identify user financial habits

This event should be fired when the payment method of a user is already entered. This event should be fired both if the payment info is explicitly requested and provided, but also if it is only implied for example when only one option is available.


Add payment info event properties

key 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.
paymentMethod YES text The method of payment that the user chooses, for example Barion, cash etc.
step YES integer It representing the current number of step in the checkout process.
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.
currency NO text (ISO 4217) The currency that the price is provided in, preferably in the three letter ISO 4217 format (eg. HUF, EUR).
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'.
opt NO text Additional information about the purchase.
orderNumber NO text The unique ID of the purchase.
positioning 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).
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.
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.

(*It's possible to add custom property)


Add payment info event implementation examples:

Click Promo (clickPromo)

  • Firing event: Button click on a promotion box only on your site.
  • User intent: View a promotion
  • Why do we need this: Users demonstrate interest in your promotion offers by clicking them

This event should be fired when one of your users selects a promotion on your site. Promotions can be usually placed on home pages, product places, in the checkout process and many other places. The promotion can be about a product, offer, brand or any other single offer or grouping of offers. This event should be implemented only on promotions that you serve on your page natively, as opposed to those served dynamically by external third party services such as Google Ads.


Click promo event properties

key required type description
contentType YES text The type of the content of the page where the promotion was selected. Possible values (only these are accepted): Page/Product/Article/Promotion/Banner/Misc.
creative YES text The name or description of the promotion, for example a promotion picture filename or slogan of the promotion.
id YES text Unique ID of the promotion clicked on your site.
name YES text Full name of the promotion.
brand NO text Brand of the item in the promotion clicked.
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 in the promotion clicked.
contents NO array An array of JS objects for detailing multiple items promoted. For more details see the table below.
currency NO text (ISO 4217) Currency that the promoted offer is listed in. 3 digit ISO 4217 format is preferred (eg. HUF, EUR).
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 promotion clicked is in from one of these possible values: HomePage/SearchPage/ProductPage/Recommendation/ComparisonPage/BasketPage/Checkout/Misc
positioning NO text The promotion's position in the list or collection (e.g. 2) or the position of the creative (e.g. banner_slot_1)
quantity NO float The quantity that the item is promoted in, measured in the unit provided (e.g. 2).
step NO integer A number that represents the progress in the checkout process.
unit NO text The measurement unit of the item promoted (e.g. pcs, kg).
unitPrice NO float Price of one unit (that you provided) of the item promoted (in the currency that you provided).
variant NO text XS') promoted.

(*It's possible to add custom property)


Click promo event implementation examples:


Sign Up (signUp)

  • Firing event: Button click that completes the registration or login process
  • User intent: Register for or login to a user account or a newsletter subscription
  • Why do we need this: Users demonstrate interest in your market area by signing up for an account

This event should be usually sent along the set user properties event in registration process, since this event only captures the actual signup, not the user itself. This event should both be fired if a user registers for an account or subscription for the first time and when they login afterwards. Unsuccessful login or signup events should cause error events to be sent. If possible, it is better if only successful attempts send a sign up event, but it is more important for all signing ups to send an event than for each signup to be only sent once.


Sign up event properties

key required type description
contentType YES text If the user signs up for a product, then it should be 'Product' else this can be 'Page' if it is a general registration or login.
id YES text This should be your unique ID for the form used to register or login.
name YES text The name of the for used for the signing up, for example 'Register' or 'Sign In'.
brand NO text The brand of the product the user signs up for.
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.
contents NO array An array of JS objects for detailing multiple items of the item. For more details 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).
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.
unit NO text The unit that your subscribed item is measured in (eg. pieces, kg, hours).
unitPrice NO float The price of one measurement of your item in the given currency.
variant NO text THehvariant 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)

(*It's possible to add custom property)


Sign up event implementation examples:


Search (search)

  • Firing event: Button click that starts a search on a page
  • User intent: Search for an offer on your page
  • Why do we need this: Users demonstrate interest in an offer by searching for it

This event is quite straightforward, every time a search button is clicked, this should send. If the search has no search button, but instead gives results on the change of the search box, then this event can be sent if the user clicks on a result. In this case, searches are sent asynchronously for partial search terms, which should not in themselves send an event. If you have a product selection page where items can be filtered, then the same can apply, the search string in this case can be the query that the settings make that can be read in your browser address bar in HTTP properties (eg. 'goats' in this: 'https://www.google.com/search?ei=A3rRXNHmJY-nrgSJs5HgDQ&q=goats').


Search event properties

key required type description
searchString YES text The search terms entered by the user or the HTTP property that contains the search terms.
contents NO array An array of JS objects containing the top ten results of your search.
contentType NO text Usually this should be 'Product'.
currency NO text (ISO 4217) If you have a filter that selects products by price, and the search string doesn't contain this, then you should provide it here.
customerValue NO float A metric that you define that measures the value of the action performed to your business.
id NO float The id of the search facility that the search is made in, for example of a search box or a filter array.
name NO text The name of the search facility that the search is made in, for example of a search box or a filter array.
totalResults NO integer The number of the search or filter results.

(*It's possible to add custom property)


Search event implementation examples:


Error (error)

  • Firing event: Any event that results in erroneous operation
  • User intent: Something else
  • Why do we need this: We can get more information about event failures

This event should be sent each time the page can't complete the requested operation, for examnple on 40x or 50x pages, failed form submissions et cetera.


Error event properties

key required type description
description YES text The description of the error, or preferably the full error message.
code NO int The error code.


Error event implementation examples:


Custom Event (customEvent)

  • Firing event: Any action that can't be described with our events
  • User intent: Something different
  • Why do we need this: We can get more information

This event is for describing any event that can't be otherwise described with our standard events.


Custom event properties

key required type description
_eventAction NO text The action that the user takes, eg. click.
_eventCategory NO text The category that the event falls in, you can define it for yourself, eg. 'user_settings'.
_eventLabel NO text The label associated with the event, eg. 'language_selection'.
_eventProperty NO text The property associated with the event, eg. 'unit_format'.
_eventValue NO text The value of the property associated with the event, eg. 'Inch'.


Custom event implementation examples:

Special properties

Contents value type - array of objects

key 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 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 or SKU.
name YES text The full name that you have for the offer, for example a product name (eg. Red Bull 24pcs carton).
quantity YES float The quantity of the product offered as initially given on the page.
totalItemPrice YES float The total price of the added items in the given currency.
unit YES text The unit that your offer is measured in (eg. pieces, kg, m).
unitPrice YES 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.
description NO text The detailed description of item.
ean NO text Contains the International Article Number (EAN) of the offer if available.
imageUrl NO text The URL of the image of the viewed item.
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)


Address value type - array of objects

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


Custom Property

name Value Type Description
_custom any type If our predefined events and/or object properties don't suit your needs, you can include your own, custom events and/or properties. Custom properties can be used with standard events. Custom properties must start with an underscore.

Custom property implementation examples:

Retrieved from "https://docs.barion.com/index.php?title=Barion_Pixel_API_reference&oldid=4260"