LANDSCAPE

track

Record a named custom event.

Record a custom event

import { init, track } from "@hyperreal/landscape-core";

init({ endpoint: "/api/events" });
track("button_clicked", { id: "cta", source: "hero" });

Signature

function track(
  name: string,
  properties?: EventProperties,
): LandscapeEvent | undefined

EventProperties is a JSON-serializable object (packages/core/src/types.ts).

Returns

The recorded event, or undefined when:

  • track runs before init
  • consent is denied
  • a validator rejects the event

Requirements

  • Names prefixed with $ are reserved ($pageview, $identify, $click, and other built-ins).
  • Automatic metadata is merged into properties before batching. Your keys override metadata on conflict.
  • With a validator from @hyperreal/landscape-schema, invalid custom events are dropped and reported via onError.

Typed arguments

import { init, getClient } from "@hyperreal/landscape-core";
import { createTypedTrack } from "@hyperreal/landscape-plugins-manual-tracking/typed";

const track = createTypedTrack(getClient()!, events);
track("signed_up", { plan: "pro" });

See Typed events. React: useTrack on React.