---
updatedAt: 2026-08-07T10:32:38.000Z
agentTools:
  siteIndex: https://documentation.bloomreach.com/llms.txt
  projectIndex: https://documentation.bloomreach.com/engagement/llms.txt
---

# Web tracking - Javascript

Integrating your business with Marketing is the first step in getting closer to your customers. Once integrated, you will immediately start getting data about your customers' behavior. If you need any assistance in deciding which API is the best for your business, please contact our integration specialist.

**Integration through Javascript** is recommended for a business based on web-browsing or for a business coded in other languages that still make use of Javascript.

# Basic integration

To integrate with Marketing using Javascript, you need to copy-paste the integration snippet into the header of your webpage. This step is an essential prerequisite for identifying your customers and tracking their actions. Read more about [the integration process here](https://documentation.bloomreach.com/engagement/docs/integration).

[block:callout]
{
  "type": "success",
  "body": "After copy-pasting the initialization code, open your business website in a new window and visit a few pages. Then open the Web integration window in the Marketing app. If you did everything correctly, it should say *Your tracking code is working*.",
  "title": "Checking if you initialized Marketing correctly"
}
[/block]

# Events

In Marketing, we distinguish between two types of events: system and custom ones. System events are automatically tracked across all projects. You can find their comprehensive list in the [**System events article**](https://documentation.bloomreach.com/engagement/docs/system-events). Custom events are the ones specifically-tailored integration for each project and you can choose whether to incorporate them. You can find some of them with examples of how to track them below. However, if you are looking for a more extensive list go to the [**Custom events article**](https://documentation.bloomreach.com/engagement/docs/custom-events).

[block:callout]
{
  "type": "info",
  "title": "Deduplication of events",
  "body": "Every tracked or imported event is checked for possible deduplication. Read more [**here**](https://documentation.bloomreach.com/engagement/docs/data-import#section-deduplication-of-events)."
}
[/block]

## Purchase

The `purchase` event tracks the basic purchase transaction of your customers. It is crucial for analyzing the overall performance of your business, evaluating campaigns, calculating the lifetime value of your customers and much more.

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description",
    "0-0": "purchase_status",
    "0-1": "string",
    "0-2": "success / fail",
    "1-0": "product_list",
    "1-1": "list - JSON (Array of objects)",
    "1-2": "List of all purchased products",
    "2-0": "total_price",
    "2-1": "number",
    "2-2": "Total value of the order",
    "3-0": "payment_type",
    "3-1": "string",
    "3-2": "cash / card / bank_transfer..."
  },
  "cols": 3,
  "rows": 4
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('purchase', {\n        purchase_status: 'success',\n        product_list: [ {product_id: \"abc123\", quantity:1} ],\n        total_price: 7.99,\n        payment_type: 'credit_card',\n        ...\n    });\n</script>\n",
      "language": "javascript",
      "name": "Example of a purchase event tracking"
    }
  ]
}
[/block]

## Purchase\_item

`purchase_item` events are generated alongside every `purchase` event and are related to every item ordered within that purchase. For example, if a customer buys 1 unit of product A and 2 units of product B within one purchase, then a single `purchase` event and two `purchase_item` events are generated.

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "0-0": "purchase_status",
    "0-1": "string",
    "0-2": "success / fail",
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description",
    "1-0": "product_id",
    "1-1": "string",
    "1-2": "Unique ID of the product",
    "2-0": "price",
    "2-1": "number",
    "2-2": "Price of 1 unit of the product",
    "4-0": "title",
    "4-1": "string",
    "4-2": "Human-readable name of the product",
    "5-0": "quantity",
    "5-1": "number",
    "5-2": "Number of items of this product bought",
    "3-0": "total_price",
    "3-1": "number",
    "3-2": "Total price paid for all units of this product",
    "6-0": "category_1",
    "6-1": "string",
    "6-2": "Top level category name (human-readable)"
  },
  "cols": 3,
  "rows": 7
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('purchase_item', {\n        purchase_status: 'success',\n        product_id: 123456,\n        price: 90,\n        total_price: 180,\n        title: 'product name',\n        quantity: 2,\n        category_1: 'category name',\n        ...\n    });\n</script>",
      "language": "javascript",
      "name": "Example of a purchase_item event tracking"
    }
  ]
}
[/block]

## Cart\_update

Event `cart_update` is tracked whenever customers add or remove a product from the shopping cart. This event is mainly used in the [abandoned cart email campaign](https://documentation.bloomreach.com/engagement/docs/cart-reactivation-email-campaign).

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "0-0": "product_list",
    "0-2": "List of all products in the cart after the last update",
    "0-1": "list - JSON (Array of objects)",
    "3-0": "action",
    "3-1": "string",
    "3-2": "add / remove",
    "4-0": "product_id",
    "4-1": "string",
    "4-2": "Unique ID of the updated product",
    "5-0": "title",
    "5-1": "string",
    "5-2": "Human-readable name of the updated product",
    "6-0": "price",
    "6-1": "number",
    "6-2": "Price of the updated product",
    "1-2": "Number of products in the cart",
    "1-0": "total_quantity",
    "1-1": "number",
    "2-0": "total_price",
    "2-1": "number",
    "2-2": "Total value of the cart",
    "7-0": "category_1",
    "7-1": "string",
    "7-2": "Top level category of the updated product",
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description"
  },
  "cols": 3,
  "rows": 8
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('cart_update', {\n        action: 'add',\n        product_list: [{item_id: \"1234\", item_quantity:3}, {item_id: \"2345\", item_quantity:2}],\n        total_quantity: 2,\n        total_price: 123.45,\n        price: 54.99,\n        title: 'Toy toy',\n        category_1: 'Party toys'\n        ...\n    });\n</script>",
      "language": "javascript",
      "name": "Example of a cart_update event tracking"
    }
  ]
}
[/block]

## View\_item

Event `view_item` tracks every view of a product page, which allows you to know how many users are interested in each product.

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "0-0": "product_id",
    "0-1": "string",
    "0-2": "Unique ID of the product",
    "1-0": "title",
    "1-1": "string",
    "1-2": "Human-readable name of the product",
    "2-0": "price",
    "2-1": "number",
    "2-2": "Price of 1 unit of the product",
    "3-0": "category_1",
    "3-1": "string",
    "3-2": "Top level category name (human-readable)",
    "4-0": "brand",
    "4-1": "string",
    "4-2": "Brand of the item",
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description"
  },
  "cols": 3,
  "rows": 5
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('view_item', {\n        product_id: '123456',\n        price: 123,\n        title: 'Lenovo ThinkPad',\n        brand: 'Lenovo',\n        category_1: 'Notebooks',\n        ...\n    });\n</script>",
      "language": "javascript",
      "name": "Example of a view_item event"
    }
  ]
}
[/block]

## View\_category

Event `view_category` tracks every view of a category page. This information is useful when determining what are the most visited categories.

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description",
    "0-0": "category_id",
    "0-1": "string",
    "0-2": "Unique identifier of the category",
    "1-0": "category_name",
    "1-1": "string",
    "1-2": "Human-readable name of the category"
  },
  "cols": 3,
  "rows": 2
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('view_category', {\n        category_id: '123456',\n        category_name: 'Notebooks'\n        ...\n    });\n</script>",
      "language": "javascript",
      "name": "Example of a category_view event tracking"
    }
  ]
}
[/block]

## Checkout

Event `checkout` is used to track several steps of the purchase process, including the customer data acquisition, payment, shipping, and the transaction thank-you page. Tracking these steps is vital for analyzing where customers drop out.

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "0-0": "step_number",
    "0-1": "number",
    "0-2": "Step of the checkout process",
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description",
    "1-0": "step_title",
    "1-1": "string",
    "1-2": "Human readable checkout process step title"
  },
  "cols": 3,
  "rows": 2
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('checkout', {\n        step_number: 2,\n        step_title: 'Shipping details'\n        ...\n    });\n</script>\n",
      "language": "javascript",
      "name": "Example of a checkout event tracking"
    }
  ]
}
[/block]

## Registration

Event `registration` is tracked when a new user registers on the website. This event allows you to keep track of customer behavior or trigger automated marketing campaigns. In combination with the 'exponea.update' function, the attributes this event tracks will be attributed directly to the customer profile.

**Overview of basic recommended attributes to track:**

[block:parameters]
{
  "data": {
    "h-0": "Attribute name",
    "h-1": "Type",
    "h-2": "Value / Description",
    "0-0": "email",
    "0-1": "string",
    "0-2": "Lower-cased and trimmed email address",
    "1-0": "first_name",
    "1-1": "string",
    "1-2": "First name",
    "2-0": "last_name",
    "2-1": "string",
    "2-2": "Last name",
    "3-0": "phone",
    "3-1": "string",
    "3-2": "International phone number format, such as +15417543010"
  },
  "cols": 3,
  "rows": 4
}
[/block]

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('registration', {\n        email: 'gordon.freeman@blackmesa.com',\n        first_name: 'Gordon',\n        last_name: 'Freeman',\n        phone: '+15417543010',\n        ...\n    });\n</script>\n",
      "language": "javascript",
      "name": "Example of a registration event tracking"
    }
  ]
}
[/block]

## Tracking list attributes

It is possible to track list attributes, that is equivalent to JS array. It is possible to use Marketing list filters with list attributes, which is not possible with objects (as shown above in cart\_update).

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.track('view_article', {\n        tags: [\"finance\", \"red\", \"...\" ]\n    });\n</script>\n",
      "language": "javascript"
    }
  ]
}
[/block]

# Customer identification

To know your customers better, you need to identify them with a unique identifier, such as e-mail or username.

## Automatic identification

Marketing automatically creates an anonymous customer when the method initialize() (e.g from [Javascript SDK](https://documentation.bloomreach.com/engagement/docs/js-sdk)) is called for the first time on a device. These customers are identified by a generated cookie which means that subsequent sessions within a single device will be tracked to the same customer.

## Multi-device identification

Apart from the automatic cookie tracking, Marketing also allows clients to track a single customer across more platforms or devices. Therefore we can, for example, connect events that customers make in the Android and iOS version of your business.

## Hard IDs

We use the method identify(hard\_id) to assign a hard ID (e.g. email address or username) to a user. When a customer with the given hard ID already exists, all customer profiles with the same ID will be merged. A new customer is created in Marketing every time a user is identified with a different hard ID. However, all previous events remain in the previous customer history.

\##Implementation
We can use the identify() method in two ways:

* identify(hard\_id);
  * identity field registered will be updated
* identify({identity: id});
  * We can save various hard IDs for a customer. However, customers are merged under every hard ID. Therefore if two customers with different `registered` are identified with the same hard ID identity field, event tracking will fail.

A good practice is to identify customers after every successful login/registration. More frequent identification may lead to problems with customer merging.

To read more about identifying customers, continue reading [the documentation for the `identify()` method](https://documentation.bloomreach.com/engagement/docs/tracking#identify).

### Multiple identities

If there are more identities (more than `registered` and `cookie`) in the project, you need to use a special identify call.

For example to identify with email\_id you call:

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.identify({ \n        email_id: \"john.smith@exponea.com\" \n    });\n</script>",
      "language": "javascript"
    }
  ]
}
[/block]

If you are identifying a customer and you know all identities, you can also identify with:

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.identify({\n        registered: \"user_id_123\", \n        email_id: \"john.smith@exponea.com\" \n    });\n</script>",
      "language": "javascript"
    }
  ]
}
[/block]

[block:callout]
{
  "type": "warning",
  "body": "If using caching on your web server, you need to make sure you do not insert the identify script into this part."
}
[/block]

# Updating the customer’s profile

In addition to tracked events, every customer in Marketing has a set of attributes. Attributes can be used to contact the customer through a personalized campaign.

Read more [in our documentation about the `update()` method](https://documentation.bloomreach.com/engagement/docs/tracking#update).

This guide should have provided you with all the basics needed to start tracking your first events and customers. We would love to help you get started as soon as possible, so if you have any questions, please contact our integration specialist.

# Advanced tracking

## Customizing default tracking

Default tracking behavior can be adjusted in the exponea.start(options) call:

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\"> \n    exponea.start({\n        token: 'PROJECT TOKEN',\n        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',\n        ping: { enabled: true}, // enables tracking session_start, first_session and session_end events\n        track: { visits: true }  // enables tracking page_visit event\n    });\n</script>",
      "language": "javascript"
    }
  ]
}
[/block]

You can also specify custom properties to be emitted with the `session_start` and `session_end` events.

[block:code]
{
  "codes": [
    {
      "code": "<script type=\"text/javascript\">\n    exponea.start({\n        token: 'PROJECT TOKEN',\n        customer: 'Insert unique identified of your customer or remove this line (so cookie identification will used)',\n        ping: {\n            // specify your custom properties here\n            properties: {\n                version: 2,\n                subdomain: 'www'\n            }\n        }\n    });\n</script>",
      "language": "javascript"
    }
  ]
}
[/block]

[block:callout]
{
  "type": "info",
  "body": "The *customer* parameter can use any object with identifier same as *exponea.identify()*. When **string** is used, it will use identifier **registered** only."
}
[/block]

## Action tracking

You can emit custom events when clicking links:

[block:code]{"codes": [{"code": "<a id=\"bloomreach_link\" href=\"http://www.bloomreach.com\">Bloomreach</a>\n\n<script type=\"text/javascript\">\n    exponea.trackLink('#bloomreach_link', 'external_link', {\n        site: 'Bloomreach'\n    });\n</script>", "language": "javascript"}]}[/block]

## Limitations

Characters . and $ are not allowed to be used in JSON keys. However, they can be used as values.

\##Bot filtering
Marketing automatically filters out bot traffic which it can identify. This currently works by default and can’t be configured on project-level basis.

\###Marketing filtering:
If customer/events is tracked with Marketing web tracking, and the message includes user-agent header with patterns from [this file](https://raw.githubusercontent.com/monperrus/crawler-user-agents/master/crawler-user-agents.json), the message is automatically neglected. The message then isn’t stored within Marketing.

\##Javascript SDK
All functionalities in a detail are described in a [Javascript SDK](https://documentation.bloomreach.com/engagement/docs/js-sdk).