Skip to main content

Analytics

A deck's own named events, recorded in its creator analytics beside Castle's built-in ones (plays, play time, players who come back).

import { Analytics } from "castle-web-sdk";

Analytics.event("level_complete", { level: 3, seconds: 41 });

Analytics.event(name, properties?): void​

Records one event for the player. Synchronous and fire and forget: it returns nothing, and a host that cannot record it (an older one, or no network) drops it without the deck noticing.

  • name is trimmed, then 1 to 64 characters of letters, digits, space and _ . : / -, starting with a letter or digit.
  • properties is optional: a plain object of at most 5 keys, each 1 to 32 characters under the same rule, whose values are finite numbers. Castle stores each as a whole number (rounded).
  • A bad name or properties throws a TypeError at the call, so a mistake shows up while you build the deck.
  • At most 60 events a minute per page load; the rest are dropped, with one console warning the first time.

An event has to be registered before players' events are kept. Castle keeps a list of event types per creator, up to 100 across all of a creator's decks. When the deck's creator plays the published deck, each Analytics.event call registers its name, with its property keys in the order the call gives them; the creator's own plays are not counted. After that, players' events with that name are recorded, carrying the properties the type names. A player's event under a name the creator never registered is dropped, as are property keys the type does not name. So play every path that sends an event once, signed in as the deck's owner, after saving the deck.

Registration is limited: at most 20 registrations per creator per hour (a new name, or a property key added to an existing name, each counts as one), and at most 100 event types per creator. A call past either limit registers nothing, so the name stays unregistered and players' events under it are dropped until the creator plays it again after the hour has passed. To see what is registered, the creatorEventTypes query in Castle's API lists the creator's event types with their property names, in slot order; createCreatorEventType registers one directly.

Only a published deck records events: on castle-web serve of a deck that was never saved, Analytics.event validates its arguments and sends nothing.

Each event carries the player's experiment arms, like the built-in events, so creatorEventStats with splitBy: EXPERIMENT reads custom events per variant.