Javascript API

This document describes the functionality available of the Crobox Javascript API.

Introduction

By pushing events to Crobox using custom code snippets per page you can easily integrate the various event tracking needed for Crobox to built the rich Product insights. By connecting those events the various metrics and real-time product information will be available.

Pageviews

On each pageview an event should be sent to to Crobox using the crobox.pageview(data: object, force?: boolean) API.

The first argument is an object with properties that are different per pagetype.

The second argument is a boolean which only should be set to true when you are using an SPI interface and you want to force a new pageview. Normally multiple pageview calls without refreshing the browser will augment each other, by using force: true it will register a new pageview instead.

Page types

Crobox uses page types to categorize types of pages together, built-in system ones are:

• index (Home Page)

• overview (Product Lister Page)

• detail (Product Detail Page)

• cart (Cart Page)

• checkout (Checkout Page)

• complete (Complete / Confirmation page)

• search (Search Result page)

• other (Fallback)

Properties available per page type

Different properties can be sent per page type in the pageview event. For example the checkout pages can have a step property where the overview pages can have a list of all product-ids currently available on that lister page. The various properties are specified for each individual page-type below.

All pages

These properties are required on all pageview events.

Property	Type	Description
pt	number	Indicates what pagetype is currently being viewed. Should be one of the built-in system pagetypes available on the crobox object: crobox.PAGE_INDEX crobox.PAGE_OVERVIEW crobox.PAGE_DETAIL crobox.PAGE_CART crobox.PAGE_CHECKOUT crobox.PAGE_COMPLETE crobox.PAGE_SEARCH
lc	string	Used to correctly identifying which country / language the pageview is for. Must be formatted with valid language and country ISO codes combined with a dash or underscore (language first). f.e. nl-NL or en-GB

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_INDEX,
    lc: "en-GB"
});

Overview pages

Product Lister pages normally contain a list of products. By specifiying the ordered list products-ids that are shown Crobox can track which products have been viewed.

Property	Type	Description
imp	string[]	Array of strings that contains the product-ids of the impressions that are shown on the overview page in the same order, f.e. ["1","2","3"]

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_OVERVIEW,
    lc: "en-GB",
    imp: [
    "123", // First product id
    "345", // Second product id
    "567", // Third product id
    .... // etc..
    ]
});

Detail pages

Product Detail Pages are centered around a single product. By sending that product-id to Crobox it can be used for example to give detailed insights about metrics like Look-to-Book ratio or Add-to-Cart rate.

Property	Type	Description
pi	string	The product-id of the product that is currently being viewed. "123"

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_DETAIL,
    lc: "en-GB",
    pi: "123"
});

Cart pages

It is important to register the product-id and quantity of the shopping-cart on cart pages. This helps Crobox to properly identify which products are added, or removed from cart.

Property	Type	Description
imp	{id: string, qty: number }[]	Array of objects containing the product-id and quantity of the products currently in the cart f.e. [{id: "1", qty: 2}, {id: "2", qty: 1}]

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_CART,
    lc: "en-GB",
    imp: [
        { id: "123", qty: 1},
        { id: "345", qty: 3},
        .... // etc..
    ] 
});

Checkout pages

Checkout pages can have multiple steps. By optionaly identifying each step you can get deeper insights of checkout behavior.

Property	Type	Description
stp	number?	Optional number that can be used to track at which step the visitor is into the checkout

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_CHECKOUT,
    lc: "en-GB",
    stp: 2
});

Complete pages

Complete pages are the most important event to push to Crobox correctly, since they are used to register which products have been bought and if the visitor has converted.

Property	Type	Description
tid	string	The order-id. This is used to uniquely identify and deduplicate a transaction / order.
rev	number	Number containing total revenue for this order
imp	{ id:string, qty: number}\[\]	Array of objects containing the id and quantity of the products being sold f.e. \[{id: "1", qty: 2}, {id: "2", qty: 1}\]

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_COMPLETE,
    lc: "en-GB",
    tid: "27493", // Order id
    rev: 162.23, // Order revenue
    imp: [
        { id: "123", qty: 1},
        { id: "345", qty: 3},
        .... // etc..
    ]
});

Search pages

Search pages can have an optional search term that was used to get to the search-results.

Property	Type	Description
st	string?	Search term that was used for the search

Code example

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.pageview({
    pt: crobox.PAGE_SEARCH,
    lc: "en-GB",
    st: "Orange running shoes"
});

Actions

Numerous actions are happening on pages at the same time. In order for Crobox to be able to provide more advanced analytics about products it is possible to set up tracking for other actions, as well. Two such actions are built-in, namely:

Impression click action

Execute this code when on a product lister page a specific product is clicked. This is so Crobox can register which products are most commonly clicked.

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.click({
    productId: "123"
});

Add-to-cart action

Execute this code when a product is added to the cart.

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.addToCart({
    productId: "123",
    quantity: 2
});

Custom actions, for example add-to-favorites

It is also possible to set up tracking for custom actions, for example when you want to track the number of times users have added a specific product to their favorites. The following logic can be used for such cases:

window.crobox = window.crobox || [];
crobox.push(function(crobox) {
    // Crobox API is now ready to used and methods are available
    crobox.track('addToFavorites', {
    productId: "123" // Optional 
})

Event system

There is an Events API available that can be used to communicate with the third-parties to have a stable connection between the Crobox Platform and the integrating party. This could be used to integrate with third-party analytics or:

Register a new event-listener on the event system

crobox.on(event, callback)

Use this method to register a new event-listener on the event system.

Argument	Type	Description
event	string	Name of the event that needs to be listened to.
callback	function	Functionality that needs to be executed when the event fires, as arguments it received the extra arguments that are added when an event is fired

De-register an existing event-listener on the event system

crobox.off(event, callback)

Use this method to de-register an existing event-listener on the event system. Note: for this, you do need to have a reference to the existing callback.

Argument	Type	Description
event	string	Name of the event that needs to be stopped listening to
callback	function	Functionality that was previously registered

Fire a new event in the event system

crobox.emit(event, args...)

Use this method to fire a new event in the event system.

Argument	Type	Description
event	string	Name of the event that you want to emit a new event for
args...	vararg	Extra argument that are passed will be add as arguments to the callback function that are registered on the event.