Registar ações no contexto

A decisão de instrumentação mais importante é como nomeia os eventos e onde coloca o contexto. Se acertar, um único evento responde a uma dúzia de perguntas; se errar, o catálogo explode em centenas de nomes quase duplicados que nenhum funil consegue alinhar. Este guia é o padrão canónico da Kixo — o mesmo modelo que o assistente de instrumentação com AI (suggest_instrumentation no chat) recomenda.

O padrão: um evento generalizado + propriedades ricas

Registe um evento por ação do utilizador e descreva o contexto com propriedades — nunca divida o nome do evento por contexto. Um post aberto a partir da pesquisa e um post aberto a partir do feed são a mesma ação (post_opened), com uma propriedade source diferente.

Antipadrão

Não não crie post_opened_from_search, post_opened_from_feed, post_opened_from_profile. Três nomes de eventos significam três coisas para manter, nenhum funil único os consegue abranger e, ao acrescentar uma quarta superfície, isso obriga a alterar código em todo o lado. Um único post_opened com source adapta-se a qualquer número de superfícies sem custo adicional.

Não faça assim (um evento por contexto)	Faça assim (um evento + uma propriedade)
`post_opened_from_search` `post_opened_from_feed`	`post_opened` com `{ source: "search" \| "feed" }`
`video_played_mobile` `video_played_web`	`video_played` — a plataforma já é incluída automaticamente em todos os eventos
`checkout_from_cart` `checkout_from_buy_now`	`cart_checked_out` com `{ source: "cart" \| "buy_now" }`

Nomenclatura: snake_case, objeto primeiro, verbo depois, no passado

Dê a todos os eventos nomes em (object)_(verb), em snake_case e no passado — post_opened, video_played, cart_checked_out. O mesmo nome deve ser usado exatamente da mesma forma em Web, iOS e Android, para que os funis multiplataforma fiquem alinhados e para que o detetor de eventos padrão da Kixo consiga reconhecer os nomes canónicos.

Objeto primeiro, verbo depois — agrupa eventos relacionados quando percorre o catálogo (post_opened, post_liked, post_shared).
Passado — um evento regista algo que aconteceu.
snake_case — não postOpened, nem PostOpened. O detetor e o comparador de vocabulário não distinguem maiúsculas de minúsculas, mas convergir para uma única forma mantém os funis limpos.

Propriedades de evento vs. propriedades de utilizador

A outra metade da decisão é onde fica um valor.

	Propriedade de evento	Propriedade do utilizador
Descreve	Esta ocorrência específica da ação	A pessoa, de forma persistente ao longo de todos os seus eventos
Definido por	`Kixo.track(name, { ... })`	`Kixo.setUserProperty(key, value)`
Exemplos	`source`, `screen`, `post_id`, `amount_cents`	`plan`, `vip`, `signup_cohort`, `lifetime_orders`
Capacidades	Filtros por passo no funil, desagregações, distribuições	Segmentação, definição de audiências-alvo, elegibilidade para campanhas

Sugestão

Regra prática: se o valor pode variar entre dois eventos do mesmo utilizador (qual post, qual origem), é uma propriedade de evento. Se é um facto sobre o utilizador que se mantém independentemente da ação (o plano, se é VIP), é uma propriedade de utilizador. Ponha source no evento; ponha plan no utilizador.

Inclua sempre um ID estável da entidade

Passe um ID estável do objeto sobre o qual a ação incidiu — post_id, video_id, order_id. Sem isso, consegue contar quantos posts foram abertos, mas não consegue agrupar, eliminar duplicados nem encadear eventos sobre o mesmo post. Um funil como pesquisa → abertura-a-partir-da-pesquisa → like só corresponde a um percurso coerente do utilizador quando cada passo inclui a propriedade que liga os vários passos.

Exemplo prático: pesquisar → abrir → gostar

Imagine que quer saber quantos utilizadores pesquisa, depois abre um post a partir dos resultados da pesquisa e depois faz like. São três eventos — mas o contexto "a partir da pesquisa" é uma propriedade de source em post_opened, não um evento separado:

search_performed — { query }
post_opened — { source: "search", screen, post_id }
post_liked — { source: "search", screen, post_id }

Depois, o funil filtra o passo 2 (e o passo 3) por source = "search" — uma única condição sobre a propriedade, sem andar a gerir nomes de eventos diferentes. Eis as chamadas exatas do SDK para cada plataforma:

// User runs a search
Kixo.track('search_performed', {
  query: 'running shoes',
});

// User taps a result — the post was opened FROM search
Kixo.track('post_opened', {
  source: 'search',          // ← context as a property, not the event name
  screen: 'search_results',
  post_id: 'post_8f3a1c',
});

// User likes the post they opened from search
Kixo.track('post_liked', {
  source: 'search',
  screen: 'post_detail',
  post_id: 'post_8f3a1c',
});

Marcar o utilizador em vez disso

Se "fez like num post a partir da pesquisa" for uma característica duradoura que quer usar na segmentação, e não apenas um sinal por evento, defina uma propriedade de utilizador depois da ação: Kixo.setUserProperty("liked_from_search", true). Assim, o explorador de audiências e a elegibilidade para campanhas podem direcionar esses utilizadores diretamente.

Deixe a AI tratar disso por si

No chat do dashboard da Kixo, descreva em linguagem natural o que quer medir — "track posts opened from search and then liked" — e o assistente devolve os eventos, as propriedades e os snippets prontos a copiar para as três plataformas. e indica-lhe que eventos já estão a chegar no seu projeto e o que ainda exige trabalho no SDK. Aplica exatamente o padrão desta página.

Veja também: Referência de eventos, com os onze nomes canónicos de eventos que a Kixo reconhece automaticamente, e os guias do SDK para Web, iOS e Android.