Custom events

Track the moments that matter in your product with datacub.track(name, properties).

datacub.track('signup_completed', { method: 'email' })
datacub.track('project_created', { template: 'blank', members: 3, trial: true })

The same call works in React Native:

import datacub from '@datacub/react-native'

datacub.track('order_placed', { items: 2, total: 149.5, currency: 'SAR' })

Call it after the action succeeds: when the server answered, the payment was confirmed, the file was saved. Not on the button click. Choosing events.

Names

  • 1 to 100 characters. Use object_action in snake case: invite_sent, report_exported.
  • Cannot start with $ (those are datacub's own events).
  • Refused when they look like an identifier: 6 or more digits in a row, 16 or more hex characters, part of a UUID, or an @. Put IDs in properties of a known type instead, or leave them out.

A refused call does nothing. On localhost the SDK prints why in the console.

Properties

Values can be strings, numbers, booleans, null, dates, arrays and objects:

datacub.track('report_exported', {
  format: 'csv',
  rows: 1200,
  scheduled: false,
  range: { from: new Date('2026-10-01'), to: new Date('2026-10-31') },
  columns: ['users', 'sessions'],
})
RuleWhat happens
Up to 200 keys per eventthe rest are dropped
Short stringsa string over 256 characters or 12 words is free text and becomes [redacted]
Objects nest 3 levelsdeeper levels become [depth]
Arraysfirst 100 items
Datessent as ISO 8601 UTC
Functions, undefined, class instances, NaN, Infinitydropped

What datacub removes on its own

Keys named like secrets or personal data are dropped: password, OTP, PIN, CVV, card number, IBAN, Iqama, national ID, token, secret, session ID, cookie and others, in English and Arabic. Values that contain an email address, 9 or more digits (phone numbers, national IDs, cards, IBANs, in any digit script), bearer tokens or long key-like strings have that part replaced by [redacted]. The server repeats every check.

This is a safety net, not a plan. Send product facts (plan, step, count, currency), never who someone is or what they typed.

Delivery

Events are batched: sent 5 seconds after the first one, at 20 events, or when the page is hidden or closed. Failed sends are retried with backoff. Each event has a unique ID, so a retry is never stored twice.