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,
});

explain(event, properties?, { userId? })

Preview what an event would trigger before you fire it. The rule engine evaluates your XP rules, currency grant rules, feed rules, streaks, and webhook subscriptions against the candidate event and returns the would-be effects — without writing anything. Nothing is granted, no feed item is created, no webhook is sent.

Use it to confirm your rules are wired the way you intend, or to show a user what an action will earn them before they take it.

const plan = await Amba.events.explain('lesson_completed', { score: 90 });
 
for (const rule of plan.matched) {
  console.log(rule.rule_type, rule.would, rule.note ?? '');
}
// xp            { xp_delta: 25 }
// currency_grant{ currency: 'coins', amount: 10 }
// streak        { period: 'daily' }

Pass { userId } to also preview per-user gating — when a rule matches but a daily limit, cooldown, or balance cap would currently suppress or reduce the effect, that entry carries a note explaining it. The preview never mutates state, so it is safe to call as often as you like.

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.