Events

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.
Custom attributes are specified via a parameters object (optional).
Custom attributes have some reserved keys. See the section "Reserved event attributes" under "Event data" for more info.

Here's an example:

// Simple event without custom data
batchSDK(api => { api.trackEvent("add_to_cart") })

// Advanced event with custom data
batchSDK(api => { 
  api.trackEvent("add_to_cart", { 
    
    // Custom attributes
    attributes: {
      
      // Your custom data
      sub_category: "bags",
      
      // Reserved key
      $label: "accessories"
    }  
  }) 
})

Event data

Custom data can be attached to events, through the attributes key, but before we get started on how to implement it, here are some rules you should know:

Attribute names are strings. They should be made of letters, numbers or underscores ([a-z0-9_]) and can't be longer than 30 characters (e.g. has_premium). They will be automatically lowercased, so trying to use the same key with different casing will overwrite the previously set value.

Values must be any of the following types:

String must not be longer than 200 characters and can't be empty. For better results, you should make them upper/lowercase and trim the whitespaces.
Float/Double by using number.
Integer/Long by using number.
Boolean
Date by using the Javascript Date object
URL by using the Javascript URL object, not longer than 2048 characters and following the scheme://[authority][path][?query][#fragment] format

≥ 4.0.0 Batch now allows the following types:

Array, You can set array of strings (max 200chars) and array of objects. Max 25 items. You cannot mix several attribute types in one array. Arrays can't be nested.
Object, Objects cannot have more than 3 levels of nesting.

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

Limits

Events support at most 20 attributes. Any value over this limit will be truncated.

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, ARRAY, OBJECT 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.
Auto-detection: Provide a value, Batch will autodetect its type. Make sure that the type fits the represented data in the most appropriate way.

Reserved event attributes

Some event attributes have reserved keys, and are all prefixed by a $ sign. This is the list of currently reserved event attributes. You cannot set an event attribute starting by a $ sign.

Id	Description
`$label`	String - Optional Event label. Must be a string, will automatically be bridged as label for application event compatibility. Max 200 chars. E.g.`{"$label":"clothing"}`
`$tags`	Array - Optional Event tags. Must be an array of string, will automatically be bridged as tags for application event compatibility. Max 10 items of type string, each no longer than 64chars. The SDK will automatically lowercase them, so two same strings with different casing do not count as two different tags E.g.`{"$tags":["first_purchase","in_promo"]}`

In Batch Web SDK v3 you were able to set a label and tags at the root of an event, with the limit of 1 label and 10 tags.

Batch Web SDK v4 introduced Object and Array types in event attributes. You can set more than one array on profiles events. This is only supported for profiles, and not on the install centric data model, which currently powers push notification and In-App messages.

However, it's still possible to set a label and tags on events in the install-centric data model by using $label and $tags, and activate compatibility flows. This way, you will be able to use this data for your push and in-app communications.

Examples


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

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

// Event with custom attributes and tags but no label
batchSDK(api => {
  api.trackEvent("validated_purchase", {
    attributes: {
      sub_category: "man_clothes", // The "string" type is autodetected
      end_of_sale_date: new Date("2022-02-08T15:00:00Z"),
      items_list: [
        {
          name: "Basic Tee",
          size: "M",
          price: 23.99,
          item_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-store.com/basic-tee",
          },
          item_image: new URL("https://batch-store.com/basic-tee/black/image.png"),
          in_sales: true
        },
        {
          name: "Short socks pack x3",
          size: "38-40",
          price: 15.99,
          url: new URL("https://batch-store.com/short-socks-pack-x3"),
          image: new URL("https://batch-store.com/short-socks-pack-x3/image.png"),
          in_sales: false
        }
      ],
      $tags:["first_purchase", "in_promo"]
    },
  });
})

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", '["*"]');

Documentation > Web > Custom data