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 "Event Data".

Here's are some examples:

BatchUser.instance.trackEvent(name: "ad_seen");
BatchUser.instance.trackEvent(name: "tab_clicked", label: "activity");

Important

Please test your implementation using our debug tool before releasing your app on the store.

Event data

Custom data can be attached to events using BatchEventData. You will then use this event when calling BatchUser.instance.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 or empty.
  • 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.
    • Booleans
    • Integers
    • Doubles
    • Dates
    • URLs (using Dart's Uri type)

Events support at most 10 tags and 15 attributes.

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

Example:

BatchEventData eventData = new BatchEventData();

eventData.addTag("sports");
eventData.addTag("squash");
eventData.addTag("daily_digest");

eventData.putBoolean("premium", true);
eventData.putString("id", "ab-123456");

BatchUser.instance
    .trackEvent(name: "read_article", label: "test_label", data: eventData);

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.

Here's an example:

BatchUser.instance.trackTransaction(20.5);

Make sure you start Batch before or after tracking your events. Otherwise, they will not be sent!

You can use this data to target users who already have or haven't made any transactions in your app yet from the dashboard. Batch also displays the income generated in your app in Batch analytics.

Tracking user location

User location can be tracked in Batch. Batch will NOT automatically collect geolocation permission or track user location. You will need to fetch the user location by your own means.

Once that is done, give the latitude/longitude to Batch:

BatchUser.instance.trackLocation(latitude: 0.4, longitude: 0.523232);

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.