Skip to main content

Event Tracking

Events are the fundamental unit of data in the B2Metric platform. An event represents a single thing that happened in your application at a specific point in time — a user opening a screen, tapping a button, completing a purchase, or anything else worth measuring. Every event has a name (what happened) and may carry properties (additional context about what happened).

The SDK exposes a single method, logEvent(), that handles all event tracking. The method is non-blocking: it enqueues the event locally and returns immediately, so you can call it from any thread or callback without worrying about performance. The actual network delivery happens in the background according to the batching rules configured in B2MetricConfig.

Basic Event​

To track a simple event, supply the event name and an optional map of properties. Property keys should be strings; values may be any of the supported property types (see below).

B2Metric.instance.logEvent('page_view', properties: {'page': 'home'});

Event with Item Properties​

For e-commerce scenarios where a single event involves multiple distinct products (an add-to-cart with two SKUs, a checkout with five line items), pass an itemProperties array alongside the regular properties. Each entry in the array represents one item, with its own id, name, price, quantity, and any other fields you want to attach. This lets the B2Metric platform analyze your event at both the order level and the line-item level.

B2Metric.instance.logEvent(
  'add_to_cart',
  properties: {'total': 3000, 'currency': 'USD'},
  itemProperties: [
    {'id': 'SKU-123', 'name': 'Running Shoes', 'price': 2850, 'quantity': 1},
    {'id': 'SKU-456', 'name': 'Socks', 'price': 150, 'quantity': 2},
  ],
);

Supported Property Types​

Property values may be of the following types: String, num, bool, DateTime, null, Map<String, dynamic>, and List<dynamic>. The SDK serializes these types into JSON automatically. Unsupported types — such as custom classes, Futures, or Streams — are dropped with a warning in the console and excluded from the event payload, so a bad value never breaks the rest of your event.

Naming Recommendations​

Event names are how you'll find and reference your data in the B2Metric, so consistency matters. A well-named event is descriptive, action-oriented, and follows a predictable pattern across your codebase. The following conventions have served other teams well:

  • Use snake_case: add_to_cart, page_view, purchase_completed
  • Prefer action-oriented names with a subject and a verb: user_signed_up, item_removed, video_played
  • Maintain a shared event taxonomy across your team — a simple document listing every event name and its properties — and keep it up to date as you add new tracking
  • Use ISO standards for fields such as currency (currency: 'USD') and country codes (country: 'TR') to keep data clean and comparable
  • Avoid embedding values in event names. Prefer one event with a property over many events with similar names — track button_clicked with a property button: 'checkout' rather than checkout_button_clicked