Links

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_INDEX,
6
lc: "en-GB"
7
});

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_OVERVIEW,
6
lc: "en-GB",
7
imp: [
8
"123", // First product id
9
"345", // Second product id
10
"567", // Third product id
11
.... // etc..
12
]
13
});

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_DETAIL,
6
lc: "en-GB",
7
pi: "123"
8
});

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_CART,
6
lc: "en-GB",
7
imp: [
8
{ id: "123", qty: 1},
9
{ id: "345", qty: 3},
10
.... // etc..
11
]
12
});

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_CHECKOUT,
6
lc: "en-GB",
7
stp: 2
8
});

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_COMPLETE,
6
lc: "en-GB",
7
tid: "27493", // Order id
8
rev: 162.23, // Order revenue
9
imp: [
10
{ id: "123", qty: 1},
11
{ id: "345", qty: 3},
12
.... // etc..
13
]
14
});

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
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.pageview({
5
pt: crobox.PAGE_SEARCH,
6
lc: "en-GB",
7
st: "Orange running shoes"
8
});

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.
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.click({
5
productId: "123"
6
});

Add-to-cart action

Execute this code when a product is added to the cart.
1
window.crobox = window.crobox || [];
2
crobox.push(function(crobox) {
3
// Crobox API is now ready to used and methods are available
4
crobox.addToCart({
5
productId: "123",
6
quantity: 2
7
});

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.