Events

Batch allows you to track events that happen in your application. They automatically keep track of their count, the last time it happened and their value.

Important
- Please read our guide on custom data before tagging your app.
- Newly tracked events are hidden by default. You will need to manually display them from the dashboard settings > "Custom data" tab.

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.
• A custom data object can be attached. See the section "Event Attributes", right under this one.
• Custom attributes have some reserved keys. See the section "Reserved event attributes" under "Event Attributes" for more info.

Here's an example:

// Simple event
batch.user.trackEvent("ad_seen");

// Event with custom attributes
batch.user.trackEvent("add_to_cart", new batch.profile.eventData()
  // Custom attributes
  .put("sub_category", "bags")
  // Compatibility reserved key
  .put("$label", "activity")
);

Event attributes

Custom attributes can be attached to events using the BatchEventAttributes class, instantiable by calling new batch.profile.eventAttributes(). You will then use them when calling batch.profile.trackEvent(). It is very similar to BatchProfileAttributeEditor.

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.
• Number.
• Boolean
• Date
• URL not longer than 2048 characters and must follow the format scheme://[authority][path][?query][#fragment]
• Array<String | BatchEventAttributes>, 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 (using BatchEventAttributes, Objects cannot have more than 3 levels of nesting.

Note: Setting a value for an existing key will overwrite it. Any attempt to add an invalid attribute will fail and the event will NOT be tracked. You can catch for a list of human-readable errors.

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 except for the following.

Id	Description
$label	String - Optional Event label. Must be a string, will automatically be bridged as label for application event compatibility. Max 200 chars.
$tags	List - 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

In Batch Cordova Plugin v5 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 Cordova Plugin v6 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.

Example:

const attributes = new batch.profile.eventAttributes()
  .put('delivery_address', new batch.profile.eventAttributes()
      .put('number', 43)
      .put('street', 'Rue Beaubourg')
      .put('zip_code', 75003)
      .put('city', 'Paris')
      .put('country', 'France'),
  )
  .put('number', 43)
  .put('date', new Date().getTime())
  .put('items_list', [
    new batch.profile.eventAttributes()
      .put('name', 'Basic Tee')
      .put('size', 'M')
      .put('price', 23.99)
      .put('item_url', new URL('https://batch-store.com/basic-tee'))
      .put('item_image', new URL('https://batch-store.com/basic-tee/black/image.png'),)
      .put('in_sales', true),
    new batch.profile.eventAttributes()
      .put('name', 'Short socks pack x3')
      .put('size', '38-40')
      .put('price', 15.99)
      .put('item_url', new URL('https://batch-store.com/short-socks-pack-x3'))
      .put('item_image', new URL('https://batch-store.com/short-socks-pack-x3/image.png'),
      )
      .put('in_sales', false),
  ])
  .put('metadata', ['first_purchase', 'apple_pay'])
  .put('$label', 'accessories')
  .put('$tags', ['first_purchase', 'in_promo']);

batch.profile.trackEvent('validated_purchase', attributes).catch(e =>
  console.log(e),
);

Tracking user location

You can natively track a user location.

You will have to wrap the location in a plain object defining:

• latitude (number)
• longitude (number)
• date (Date, optional)
• precision (number, optional) precision radius in meters

Here it's typescript definition of the object:

/**
 * Represents a locations, using lat/lng coordinates
 */
interface Location {
  /**
   * Latitude
   */
  latitude: number;

  /**
   * Longitude
   */
  longitude: number;

  /**
   * Date of the tracked location
   */
  date?: Date;

  /**
   * Precision radius in meters
   */
  precision?: number;
}

And some examples:

batch.profile.trackLocation({ latitude: 2.5, longitude: 4 });

batch.profile.trackLocation({
  date: new Date(1520352788000),
  latitude: 2,
  longitude: 4.5
});

batch.profile.trackLocation({
  date: new Date(1520352788000),
  latitude: 2,
  longitude: 4.5,
  precision: 10
});

This data will allow you to send geotargeted push notifications from the dashboard or the Campaigns API.

The SDK will throttle location tracking to optimize network and battery usage. You can track one location event every 30 seconds, any attempt at updating the location sooner will be ignored by the SDK.