このモジュールでは、イベントとプロパティ（すべてのトラッキング対象イベントに自動的に付加される、永続的なキーと値のペア）を管理できます。

スーパープロパティはローカルに保存され、イベントをトラッキングするときに各イベントのペイロードにマージされます。

OpenReplay の UI でのイベント管理について詳しくは、データ管理をご覧ください。

利用可能な場所：

tracker.analytics.events

スーパープロパティは SDK 内に保存され、すべてのイベントの properties にマージされます。

イベントプロパティは、track/sendEvent の 1 回の呼び出しにのみ渡され、スーパープロパティとして保存されません。

ヘルパーに応じて、2 種類の異なるキーのセットが拒否されます：

デフォルトプロパティ：SDK 自身が収集し、すべてのイベントとともに送信されるプロパティです。setProperty はこれらを無言でスキップするため、スーパープロパティでこれらを上書きすることはできません：

os, os_version, browser, browser_version, platform, screen_height, screen_width, initial_referrer, utm_source, utm_medium, utm_campaign, user_id, distinct_id, sdk_edition, sdk_version, timezone, search_engine

ペイロードキー：properties、token、timestamp です。これらはイベントエンベロープの一部であるため、setPropertiesOnce と unsetProperties はこれらをスキップします。

// 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",
})

これらのプロパティは、このイベントにのみ適用されます。

スーパープロパティを設定すると、それらは各イベントに自動的に含まれ、その後イベント単位のプロパティとマージされます：

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", 
})

マージ順序：

• スーパープロパティが最初に追加されます
• イベント単位のプロパティがその上にマージされます

そのため、キーが衝突した場合は、イベント単位のプロパティが優先されます。

スーパープロパティを作成または上書きします。

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

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

• SDK が収集するデフォルトプロパティは無視され、スーパープロパティとして追加されません。
• キーと値の形式は、value が undefined の場合は無視されます。空の値を保存するには null を渡します。
• 変更は、実際に何かが変更された場合にのみローカルに保存されます。

スーパープロパティを、まだ存在しない場合にのみ作成します。

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

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

• プロパティは、キーが存在しない場合にのみ設定されます。
• 予約済みキー（properties、token、timestamp）は無視されます。

1 つ以上のスーパープロパティを削除します。

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

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

• 予約済みキーは削除できません。
• 削除は永続化されます。

すべてのスーパープロパティをクリアします。

tracker.analytics.events.reset()

デフォルトでは、イベントはキューに入れられ、バッチ処理されます。イベントの即時送信をリクエストすることもできます：

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

すべてのメソッドで、使い慣れた形で利用できるよう互換レイヤーが提供されています：

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

問題が発生した場合は、Slack に参加して、コミュニティのサポートを受けてください。