Events and properties

There is no schema to design here and no pipeline to run. You make one of four calls, Talaria fills in the envelope, and the row lands in ClickHouse. The part that needs thought is not the plumbing — it is what you call things.

The four kinds

• track — a named thing someone did. This is the one you will use most. The name is required.
• page — a web pageview. Defaults to the name $pageview.
• screen — a mobile or desktop screen view, defaulting to $screen. On the web it is mapped to a pageview for you.
• identify — binds the current anonymous visitor to a user id. Covered in Visitors, sessions, and identify.

Talaria.analytics.track('add_to_cart', {
  sku: 'TR-900',
  price: 129,
  size: 'M',
});

Talaria.analytics.page();                // $pageview for the current URL
Talaria.analytics.page('Pricing');       // named pageview
Talaria.analytics.track('plan_upgraded', { from: 'team', to: 'business' });

What every event carries for free

You pass a name and some properties. The SDK attaches the rest, which is why analytics events are useful long after you wrote the call:

• Identity — anonymousId, sessionId, and userId once the visitor has been identified.
• Page context — url, path, title, and referrer, with sensitive query parameters already stripped.
• First-touch campaign — the five UTM fields captured when the session began. See UTM and attribution.
• Build context — platform, environment (stamped from the API key), and release (the version or SHA the SDK sends).
• Correlation — replayId, traceId, and spanId for whatever was in flight when the event fired.
• Runtime — parsed browser name and major version, OS, device class, locale, timezone, and traffic class (human, crawler, ai_crawler, ai_agent, automation). Country and region are added at ingest from GeoIP; the IP and raw User-Agent are discarded.

Naming that survives a year

Event names are effectively permanent. Once three dashboards, two funnels, and a quarterly report use Checkout Started, renaming it to checkout_started means a gap in your history. Pick a convention on day one and write it down.

• Use object_verb in past tense: cart_updated, invite_sent, order_completed. It sorts sensibly and reads as a fact.
• Keep names low-cardinality. The product id belongs in a property, never in the name — product_viewed with { product_id }, not product_TR900_viewed.
• Reserve the $ prefix for Talaria. $pageview, $screen, and $identify are the built-in defaults.
• Name the user intent, not the implementation. signup_completed outlives the component that fired it; submit_button_clicked does not.

Properties

Properties are a flat JSON map you attach to an event. Use them for the dimensions you will want to slice by later: plan, currency, variant, step, count. Keep values scalar — numbers, booleans, and short strings — because anything else is coerced to a string on the way in.

The limits are enforced on the server, not the client:

• At most 64 keys per event. Extra keys are dropped.
• String values longer than 1024 characters are truncated at 1024.
• If the whole property map exceeds 16 KB of JSON, the entire map is discarded — the event itself is still stored, without properties.

Oversized properties do not get partially trimmed; they get dropped whole. Do not put a serialized cart, a stack trace, or an HTML blob in a property.

What gets stripped before storage

Some keys never make it to disk, no matter what you pass. The server drops properties named password, passwd, secret, token, api_key, apikey, access_token, auth, authorization, cookie, email, credit_card, card_number, and ssn.

URLs get the same treatment on both sides: the browser replaces secret and click-id query parameters before sending, and the server redacts them again on arrival.