Esquema de eventos
O esquema de eventos descreve quais eventos devem chegar ao projeto e com quais propriedades: order_completed com um montante numérico obrigatório, currency apenas EUR ou USD. O OneTrace.pro compara cada evento com o esquema e mostra as violações: um erro de digitação no nome do evento, um montante enviado como texto, uma propriedade ausente. Erros de rastreamento do site ou de uma integração aparecem na hora, e não quando um segmento ou relatório já foi calculado errado.
Um evento que viola o esquema ainda é aceito e chega ao perfil: os dados não se perdem, mesmo que o erro esteja no próprio esquema. O esquema de eventos está disponível a partir do plano “Crescimento”.
Como descrever os eventos
Abra o Catálogo de dados e a aba Esquema de eventos. O esquema pode ser alterado pelas funções com a permissão “Gerenciar o catálogo de eventos” — “Gerente” e acima; as demais veem o esquema e as violações.
- Clique em Adicionar eventos atuais — todos os eventos do catálogo entram no esquema com suas propriedades e os tipos identificados. Ou adicione os eventos um a um com o botão Adicionar evento.
- Confira as propriedades de cada evento:
| Coluna | O que define |
|---|---|
| Propriedade | A chave da propriedade como o site ou o servidor a envia, por exemplo amount |
| Tipo | Texto, número, sim/não, data e hora, lista ou objeto. Um valor de data e hora também é aceito em uma propriedade de texto |
| Obrigatória | Um evento sem essa propriedade ou com valor vazio é uma violação |
| Valores permitidos | Separados por vírgula, apenas para texto e números. Um valor fora da lista é uma violação; maiúsculas e minúsculas fazem diferença: eur e EUR são valores diferentes |
| Descrição | Para desenvolvedores: o que a propriedade significa |
- Remova os eventos e as propriedades que não devem mais chegar: se chegarem, será uma violação “Evento não descrito” ou “Propriedade não descrita”.
- Clique em Salvar esquema e ative Validar eventos pelo esquema.
As alterações se acumulam na tela e são salvas juntas. Depois de salvar, os contadores de violações recomeçam do zero: os anteriores se referem ao esquema antigo. Na aba Eventos, um evento do esquema que nunca chegou é marcado como “Ainda não recebido”, e os eventos do esquema têm a marca “No esquema”.

Os eventos de sistema da plataforma ($identify, $page, $message_sent e outros), assim como identify e as visualizações de páginas e telas do aplicativo, não são verificados: o esquema deles é definido pela plataforma.
Violações
| Violação | Exemplo |
|---|---|
| Evento não descrito | Chegou product_viewd em vez de product_viewed |
| Propriedade não descrita | order_completed chegou com a propriedade coupon, que não está no esquema |
| Falta propriedade obrigatória | add_to_cart sem quantity |
| Tipo incorreto | O montante chegou como texto "1250" em vez do número 1250 |
| Valor não permitido | currency = eur, mas o esquema prevê EUR e USD |
As violações dos últimos 7 dias aparecem acima da lista de eventos do esquema: quantas vezes e quando foi a última, com um exemplo — o tipo do valor ou o próprio valor não permitido. Sem permissão para ver dados pessoais, o exemplo é mascarado. Se o evento não está descrito por um erro do esquema, e não do rastreamento, clique em Adicionar ao esquema — ele entra no rascunho com as propriedades do catálogo.
As mesmas violações e o gráfico de eventos com violações em 24 horas ficam na seção Diagnóstico.

Importação, exportação e API
Exportar JSON baixa o esquema salvo, Importar JSON carrega um arquivo no rascunho — revise-o e salve. Assim o mesmo esquema é levado de um projeto para outro: por exemplo, para todas as lojas de uma rede ou de um projeto de teste para o de produção.
Pela API pública, o esquema é lido (GET /api/v1/event-schema) e substituído por inteiro (PUT /api/v1/event-schema, permissão da chave “Alterar o esquema de eventos”), e as violações da semana são obtidas com a requisição GET /api/v1/event-schema/violations. O formato do arquivo e da API é o mesmo:
{
"enabled": true,
"events": [
{
"name": "order_completed",
"label": "Fez um pedido",
"properties": [
{ "key": "amount", "type": "number", "required": true },
{ "key": "currency", "type": "string", "required": true, "values": ["EUR", "USD"] }
]
}
]
}
Os eventos que não estão no documento saem do esquema, mas continuam no catálogo de dados com seus rótulos e estatísticas. Um documento sem events apenas ativa ou desativa a validação.