Skip to main content

Event Tracking

Event tracking is the primary purpose of the SDK. Once init has resolved, you can call logEvent anywhere in your app to record a user action. Calls are synchronous and very cheap — the actual network delivery happens later, in the background, in batches.

5.1 Basic Event​

An event has a name (a short string that identifies the action) and an optional set of properties (a flat key/value map of context for the event). Event names should be lowercase and use underscores; this convention matches how they are displayed in the B2Metric project.

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

B2Metric.logEvent('button_click', {
  properties: { screen: 'home', button: 'cta_primary' },
})

5.2 Event with Item Properties​

When an event involves a list of things — for example, a cart with several products, or a search result containing multiple matches — pass the list as itemProperties. This is a separate field from properties so that B2Metric can analyse the list items independently of the top-level event context.

B2Metric.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 },
  ],
})

In the example above, the total and currency describe the cart as a whole, while each entry in itemProperties describes one product within it. There is no fixed schema for either map — use whatever fields make sense for your product, as long as the keys are stable across calls.

5.3 Supported Property Value Types​

Property values may be of the following JavaScript / TypeScript types:

  • string, number, boolean
  • Date — serialized to ISO 8601 format before delivery.
  • null and undefined — accepted but omitted from the payload.
  • Plain objects and arrays — serialized as nested JSON.

Values of unsupported types — for example function, Map, Set, or class instances with custom prototypes — are dropped before the event is queued, and a warning is logged when logLevel is set to warning or higher. The event itself is still delivered without the offending property.

5.4 Naming Conventions​

There is no schema enforcement on event names or property keys; the SDK will accept anything that is a non-empty string. That said, consistency makes downstream analysis significantly easier. We recommend:

  • Event names: lowercase, snake_case, present tense, verb-first when describing actions. Good: add_to_cart, complete_signup. Avoid: AddedToCart, signup completed.
  • Property keys: lowercase, snake_case, descriptive but concise. Good: screen, button_id, currency. Avoid: scr, buttonIdentifier.
  • Currencies as ISO 4217 codes (USD, EUR, TRY), prices as numbers rather than formatted strings (use 2850 or 28.50, not "$28.50").
  • Event name length is capped at 255 characters. In practice, keep names well under 50.