Events

This module lets you manage events and properties — persistent key/value pairs that are automatically attached to every tracked event.

Super properties are stored locally and merged into each event payload when you track events.

To learn more about managing events in the OpenReplay UI, visit Data Management.

Available at:

tracker.analytics.events

Super properties are stored in the SDK and merged into every event under properties.

Event properties are passed only for a single call to track/sendEvent and are not saved as super properties.

These keys are reserved and cannot be created/removed via the super properties helpers:

• properties
• token
• timestamp

// Track an event.
// The `properties` argument is per-event only (not persisted).
tracker.analytics.events.sendEvent(eventName: string, properties?: Record<string, any>, options?: { send_immediately: boolean })

// Create/update super properties (persisted)
tracker.analytics.events.setProperty(name: string, value: any): void
tracker.analytics.events.setProperty(properties: Record<string, any>): void

// Create super properties only if they don't exist yet (persisted)
tracker.analytics.events.setPropertiesOnce(name: string, value: any): void
tracker.analytics.events.setPropertiesOnce(properties: Record<string, any>): void

// Remove super properties (persisted)
tracker.analytics.events.unsetProperties(name: string): void
tracker.analytics.events.unsetProperties(names: string[]): void

// Clear all super properties
tracker.analytics.events.reset(): void

tracker.analytics.events.sendEvent("Button Clicked", {
  button_text: "Start",
  page: "home",
})

These properties apply only to this event.

When you set super properties, they are automatically included in each event and then merged with per-event properties:

tracker.analytics.events.setProperty({
  app_version: "1.42.0",
  env: "prod",
})

tracker.analytics.events.sendEvent("Signup Started", {
	// per-event, can override a super property with the same key
  plan: "pro", 
})

Merge order:

• super properties are added first
• per-event properties are merged on top

So per-event properties win on key collisions.

Creates or overwrites super properties.

// object form
tracker.analytics.events.setProperty({
  app_version: "1.42.0",
  region: "eu",
})

// key/value form
tracker.analytics.events.setProperty("build_sha", "3f2c9a1")

• Default/internal keys (tracked by the SDK) are ignored and won’t be added as super properties.
• Changes are saved locally only if something actually changed.

Creates super properties only if they do not exist yet.

tracker.analytics.events.setPropertiesOnce({
  first_seen_at: Date.now(),
  signup_source: "docs",
})

// key/value form
tracker.analytics.events.setPropertiesOnce("initial_referrer", document.referrer)

• Properties are only set if the key is missing.
• Reserved keys (properties, token, timestamp) are ignored.

Removes one or more super properties.

// single
tracker.analytics.events.unsetProperties("region")

// multiple
tracker.analytics.events.unsetProperties(["app_version", "build_sha"])

• Reserved keys cannot be removed.
• Removal is persisted.

Clears all super properties.

tracker.analytics.events.reset()

By default, events are queued/batched. You can request an immediate send for an event:

tracker.analytics.events.sendEvent(
  "Checkout Completed",
  { value: 199, currency: "EUR" },
  { send_immediately: true },
)

All methods support compatibility layer provided for familiarity:

tracker.analytics.events.register       // setProperty
tracker.analytics.events.register_once  // setPropertiesOnce
tracker.analytics.events.unregister     // unsetProperties
tracker.analytics.events.track          // sendEvent

If you encounter any issues, connect to our Slack or check out our Forum and get help from our community.