# Events (V3)

WARNING: This page only concerns the Batch Web SDK V3 and is deprecated since V4 is out. You should think to migrate on the latest version.

Batch allows you to track events that happen in your website. Batch Web SDK v3 or higher is required to use this feature.

> **Important**\
> \- Please [read our guide](https://doc.batch.com/getting-started/other/overview-guides/01-custom-data#using-your-custom-data) on custom data before tagging your website.\
> \- Newly tracked events are hidden by default. You will need to manually display them from the dashboard settings > ["Custom data" tab](https://github.com/BatchLabs/product.tech-documentation-gitbook/blob/master/guides/custom-data/README.md#using-your-custom-data).\
> \- Web events can not be used for targeting purposes like their app counterparts: they act as triggers for [Trigger campaigns](https://doc.batch.com/getting-started/features/dashboard/03-push/03-timing-delivery).

### Tracking events

Events are easy to use, but have some rules:

* Event names are strings. They should be made of letters, numbers or underscores *(\[a-z0-9\_])* and can't be longer than 30 characters.
* They can have a label, which is a string that can't be longer than 200 characters *(optional)*.
* Custom attributes and tags can be attached. See the section "Event Data", right under this one *(optional)*.

Labels, tags and attributes are specified via a parameters object.

Here's an example:

```javascript
batchSDK(api => { api.trackEvent("add_to_cart") })
batchSDK(api => { api.trackEvent("add_to_cart", { label: "accessories" }) })
```

#### Event data

Custom data can be attached to events. They support setting the following data:

* Tags: a collection of string values
  * They can't be longer than 64 characters, empty, null or undefined.
  * The SDK will automatically lowercase them, so two same strings with different casing do not count as two different tags.
* Attributes: key/value pairs of data
  * Attributes associate values to keys.
  * Keys should be made of letters, numbers or underscores (\[a-z0-9\_]) and can't be longer than 30 characters.\
    They will be lowercased, so trying to use the same key with different casing will overwrite the previously set value.
  * Values can be of the following types:
    * Strings, not longer than 64 characters, can't be empty or null.
    * Booleans
    * Floats/Doubles, using `number`
    * Integer/Longs, using `number`
    * Dates, using the [Javascript `Date` object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Date)
    * [URLs](https://developer.mozilla.org/docs/Web/API/URL), not longer than 2048 characters and following the `scheme://[authority][path][?query][#fragment]` format

Events support **at most** **10 tags** and **15 attributes**. Any value over this limit will be truncated.

Any attempt to add an invalid tag or attribute will be rejected: the tag or attribute will be removed from the data, but the event will still be tracked.

**Attribute typing**

The type of your values is important: when exploiting your events in campaigns, the operations available on your attributes are optimized for their type. As attributes are not converted by our servers, their type must be properly defined when tracking it from the SDK.

Batch handles attribute typing in two ways:

* Explicit typing: Provide both a value and a type. This is the recommended approach.\
  Available types are `STRING, BOOLEAN, FLOAT, INTEGER, DATE, URL` and their constants are available in `api.eventAttributeTypes`.\
  Since the type is explicit, Batch will attempt to convert the value to the requested type (example: a INTEGER typed value passed as a string will be converted to a number).\
  Always try to use the right value type rather than relying on this feature: If the value cannot be safely converted, the attribute will be ignored.
* Autodetection: Provide a value, Batch will autodetect its type. Make sure that the type fits the represented data in the most appropriate way.

**Example**

```javascript

// Event with a label, but no attributes or tags
batchSDK(api => { api.trackEvent("add_to_cart", { label: "accessories" }) })

// Event with tags and a label, but no attributes
batchSDK(api => {
  api.trackEvent("add_to_cart", {
    label: "accessories",
    tags: ["winter-sale", "woman"],
  });
})

// Event with attributes, tags but no label
batchSDK(api => {
  api.trackEvent("add_to_cart", {
    attributes: {
      "sub_category": "bags", // The "string" type is autodetected
      "product_page_url": {
        type: api.eventAttributeTypes.URL,
        // As the URL type has been explicitly defined, the value can be sent as a String, Batch
        // will take care of converting it.
        value: "https://batch.com/product-page",
      },
      "end_of_sale_date": new Date("2022-02-08T15:00:00Z"),
    },
    tags: ["winter-sale", "woman"],
  });
})

```

### Debugging

Event tracking errors are hidden by default. It can be useful to enable them in development/testing, as they will show if tracked events have been discarded due to validation errors.

To do so, open your developer tools and paste the following in the console:

```js
window.localStorage.setItem("com.batch.private.logger.level", "4");
window.localStorage.setItem("com.batch.private.logger.modules.enabled", '["*"]');
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.batch.com/developer/sdk/web/legacy-documentation/custom-events-v3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.