Events

Send analytics events from any platform with events.track(event, properties). Events are attributed to the currently signed-in user and stored against your project for engagement queries, segment evaluation, and outbound webhook delivery.

Events require an authenticated session. Sign the user in first — anonymous, email, or social — then track.

Quick start

import { Amba } from '@layers/amba-web';
 
await Amba.auth.signInAnonymously();
await Amba.events.track('app_opened', { source: 'direct' });

Operations

track(event, properties?)

Sends one event. Properties are optional and accept any JSON-serializable shape — nested objects, arrays, booleans, numbers, strings. Returns when the server has accepted the event.

await Amba.events.track('signup_completed', {
  plan: 'pro',
  referrer: 'twitter',
  trial_days: 14,
});

Track on mount (React)

For page-view tracking that fires once when a component mounts:

import { useTrackOnMount } from '@layers/amba-react';
 
function CheckoutPage() {
  useTrackOnMount('checkout_viewed', { cart_total: 9900 });
  return <div>...</div>;
}

Failures are swallowed so a flaky network doesn't crash render.

Patterns

Event naming

Use lowercase_snake_case and group by domain prefix. Past-tense verbs read best when you query them later:

signup_completed
checkout_started
checkout_completed
checkout_abandoned
push_clicked

Property shape

Top-level property keys should be flat and queryable. Reserve nested objects for payload data you don't plan to filter on:

// Good — flat, queryable
await Amba.events.track('order_placed', {
  order_id: 'ord_123',
  total_cents: 9900,
  item_count: 3,
});
 
// Also fine — nested payload for context
await Amba.events.track('order_placed', {
  order_id: 'ord_123',
  total_cents: 9900,
  shipping: { country: 'US', method: 'standard' },
});

Pre-auth attribution

Events sent before any sign-in are rejected with an authentication error. If you need to capture pre-signup activity, mint an anonymous session first — the same session token follows the user through email/social sign-in:

await Amba.auth.signInAnonymously();
await Amba.events.track('landing_viewed');
// later, after the user signs up...
await Amba.auth.signInWithEmail(email, password);
await Amba.events.track('signup_completed');
// Both events are attributed to the same user.

Limits

• Event name length: up to 128 characters.
• Properties payload size: up to 64 KB JSON-encoded per event.
• Authentication required: every track call needs a live session token. Calls without one return 401 Unauthorized — session token missing or expired.
• Rate limits: events accept bursts up to 100 per second per session token. Beyond that the server returns 429 Too Many Requests and the SDK surfaces the error to your caller.

Reference

• Client API — events — endpoint reference.
• Auth feature — sign-in is a prerequisite.
• Per-platform quickstart pages: Web, Node, iOS, Android, Flutter, Unity.