Events (V3)

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 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.
- Web events can not be used for targeting purposes like their app counterparts: they act as triggers for Trigger campaigns.

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:

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
    • URLs, 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

// 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:

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