Documentation > Cordova > Custom data

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.
  • They can have a label, which is a string that can't be longer than 200 bytes (optional).
  • A custom data object can be attached. See the section "Event Data", right under this one.

Here's an example:

batch.user.trackEvent("ad_seen");
batch.user.trackEvent("tab_clicked", "activity");

Event data

Starting with Batch SDK 2.1.0, you can attach custom data to events using the BatchEventData class, instanciable by calling new batch.user.eventData() You will then use this event when calling batch.user.trackEvent(). It is very similar to BatchUserDataEditor.

It supports setting the following data:

  • Tags: a collection of string values
    • They can't be longer than 64 characters, empty or null.
    • The SDK will automatically lowercase them, so two same strings with different casing does 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
      • Integer/Longs
      • ≥ 3.0.0 Dates
      • ≥ 5.1.0 URLs, not be longer than 2048 characters and followowing the scheme://[authority][path][?query][#fragment] format

An event supports at most:

≥ 3.0.0 10 tags and 15 attributes.

≥ 2.1.0 10 tags and 10 attributes.

Any attempt to add an invalid tag or attribute will fail. Setting a value for an existing key will overwrite it.

Example:

let data = new batch.user.eventData();
data.addTag("sports");
data.addTag("squash");
data.addTag("daily_digest");

data.put("premium", true);
data.put("id", "123456");
data.put("date", new Date()); // Make sure you use a Date instance and not a number. For example, `Date.now()` won't track a date.
data.put("url", new URL("https://batch.com")); // Make sure you use a URL instance rather than a string.
batch.user.trackEvent("read_article", null, data);

Note: Event data was available before Batch SDK 2.1.0, and worked with a plain JS object. This method has been deprecated: BatchEventData must now be used to describe your custom data.

Migrating from old event data

Event data tracked using the legacy API will be converted to the new format, after logging a warning.

There are a couple of limitations:

  • Any data that can't be represented using BatchEventData will be ignored.
  • Same size limits apply (key naming, string attribute length, number of attributes)

Tags are not migrated from arrays found in the legacy data format.

In order to use the new API, you will have to rewrite the code putting data in what used to be a plain JS Object to use BatchEventData.
The put method supports setting strings, booleans and numbers Consider using tags rather than tracking multiple events sharing the same name, but with different labels.

Here is an example of migrating to the new format:

// Old code
batch.user.trackEvent("ad_seen", null, {
  "utm_campaign": "thanksgiving_promo"
});

// Should be replaced by
let data = new batch.user.eventData();
data.put("utm_campaign", "thanksgiving_promo");
batch.user.trackEvent("ad_seen", null, data);

Tracking transactions

We also have a specialized kind of events: Transactions.

They let you track a transaction of a certain amount, without any currency attached: You will need to make sure you only track comparable values.

They also have some rules:

  • Amount should be a number.

Here's an example:

batch.user.trackTransaction(20.5);

Tracking user location

Starting with Batch 2.0.0, you can now 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.user.trackLocation({ latitude: 2.5, longitude: 4 });

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

batch.user.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.

Platform

Company

Resources

Contact