Este módulo permite gerenciar eventos e propriedades — pares chave/valor persistentes que são anexados automaticamente a cada evento rastreado.

As super properties são armazenadas localmente e mescladas ao payload de cada evento quando você rastreia eventos.

Para saber mais sobre como gerenciar eventos na interface do OpenReplay, acesse Data Management.

Disponível em:

tracker.analytics.events

As super properties são armazenadas no SDK e mescladas a cada evento em properties.

As propriedades de evento são passadas apenas em uma única chamada de track/sendEvent e não são salvas como super properties.

Dois conjuntos diferentes de chaves são rejeitados, dependendo do helper:

Propriedades padrão — coletadas pelo próprio SDK e enviadas com cada evento. setProperty as ignora silenciosamente, então você não consegue sobrescrevê-las com uma super property:

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

Chaves de payload — properties, token e timestamp. Elas fazem parte do envelope do evento, então setPropertiesOnce e unsetProperties as ignoram.

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

Essas propriedades se aplicam apenas a este evento.

Quando você define super properties, elas são incluídas automaticamente em cada evento e depois mescladas com as propriedades por evento:

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

Ordem de mesclagem:

• as super properties são adicionadas primeiro
• as propriedades por evento são mescladas por cima

Assim, as propriedades por evento prevalecem em caso de colisão de chaves.

Cria ou sobrescreve 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")

• As propriedades padrão coletadas pelo SDK são ignoradas e não serão adicionadas como super properties.
• A forma chave/valor é ignorada quando value é undefined; passe null para armazenar um valor vazio.
• As alterações são salvas localmente somente se algo realmente mudou.

Cria super properties somente se elas ainda não existirem.

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

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

• As propriedades só são definidas se a chave estiver ausente.
• As chaves reservadas (properties, token, timestamp) são ignoradas.

Remove uma ou mais super properties.

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

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

• As chaves reservadas não podem ser removidas.
• A remoção é persistida.

Limpa todas as super properties.

tracker.analytics.events.reset()

Por padrão, os eventos são enfileirados/agrupados em lotes. Você pode solicitar o envio imediato de um evento:

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

Todos os métodos oferecem suporte a uma camada de compatibilidade, fornecida por familiaridade:

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

Se você encontrar algum problema, conecte-se ao nosso Slack e peça ajuda à nossa comunidade.