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.

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.