Eventos, definições e propriedades
Um evento registra algo que aconteceu. A definição garante o formato combinado entre sua integração e o PrismaFlow.
Uma boa definição não é a que possui mais campos. É a que protege os campos importantes para a operação.
O que é um evento
Um evento é um acontecimento enviado ao PrismaFlow. Ele informa:
- o que aconteceu;
- qual versão do contrato está sendo usada;
- quando aconteceu;
- quem está relacionado ao acontecimento;
- quais dados descrevem aquele momento.
O nome deve deixar o acontecimento claro. conta_aberta, kyc_aprovado e pix_recebido são exemplos de nomes que mostram algo que já aconteceu.
Cada envio possui cinco partes principais:
| Parte | Para que serve |
|---|---|
name | Identifica o acontecimento. |
version | Indica qual versão da definição deve validar o evento. |
timestamp | Registra quando o acontecimento ocorreu. |
identifiers | Ajuda o PrismaFlow a reconhecer a pessoa de forma protegida. |
properties | Guarda os dados que descrevem o acontecimento. |
O evento também pode possuir context. Nas SDKs — bibliotecas que facilitam a integração — de navegador ou aplicativo, esse bloco costuma ser preenchido automaticamente com informações gerais do ambiente. Em uma integração server-side, executada no servidor, ele pode ser informado manualmente.
O que é uma definição
A definição é o contrato de dados entre sua integração e o PrismaFlow.
Ela combina o nome e a versão do evento com as regras de suas propriedades. Esse conjunto de campos, tipos e regras forma o schema. Assim, o PrismaFlow consegue conferir se os campos importantes chegaram e se possuem o formato esperado.
Uma definição pode informar:
- quais propriedades são aceitas;
- o tipo de cada propriedade;
- quais propriedades são obrigatórias;
- se campos não declarados podem passar;
- descrição e tags para facilitar a organização;
- se aquela definição está ativa.
Se o evento usa uma combinação de nome e versão que não possui definição ativa, ele não segue o fluxo normal. Os motivos e caminhos de recuperação estão no guia de quarentena de eventos [blocked].
Tipos e normalização dos valores
O tipo declarado na definição não serve apenas para encontrar erros. Ele também ajuda o PrismaFlow a normalizar valores compatíveis antes de armazená-los.
Por exemplo, se amount foi definido como número e a integração enviar "10", o PrismaFlow consegue interpretar e armazenar o valor como 10. A definição transforma uma informação ambígua da origem em um dado com tipo conhecido para os próximos usos.
Essa normalização é importante porque segmentos, computed traits e jornadas precisam comparar valores de forma coerente. Um valor que pode ser convertido com segurança segue o contrato normalizado. Um conteúdo incompatível, como "dez" em um campo numérico, não se torna válido apenas porque o campo possui uma definição.
Uma definição completa ou enxuta?
As duas estratégias são válidas. A escolha muda o nível de garantia da operação.
Contrato governado
Use uma definição bem construída quando você conhece os dados e quer detectar problemas cedo.
Declare os campos importantes e use validação strict. Um campo inesperado, ausente ou com tipo incorreto pode ser identificado antes de afetar segmentos, computed traits ou jornadas.
Essa estratégia ajuda quando você precisa:
- garantir que os filtros dos segmentos recebam os dados esperados;
- perceber rapidamente que uma integração mudou;
- evitar resultados silenciosamente incompletos;
- investigar onde o contrato deixou de ser cumprido.
Descoberta controlada
Alguns clientes recebem eventos com muitos campos, formatos variáveis ou alta cardinalidade. Nesses casos, eles podem começar declarando apenas um campo que sabem que estará sempre presente e usar validação lenient.
Os outros campos continuam chegando e aparecem no catálogo de propriedades. Esse catálogo alimenta sugestões e autocompletes dentro do PrismaFlow.
Essa estratégia reduz o trabalho inicial, mas também reduz as garantias. Um campo usado por um segmento pode deixar de chegar sem que a definição o considere obrigatório.
Use a descoberta controlada de forma consciente. Conforme os campos importantes ficarem claros, avalie incluí-los no contrato.
strict e lenient
No modo strict, o evento precisa respeitar o schema declarado. Campos adicionais não são aceitos.
Use strict quando:
- a integração possui um contrato bem definido;
- você conhece os campos enviados;
- um dado ausente ou inesperado precisa chamar atenção;
- as automações dependem de garantias mais fortes.
No modo lenient, o evento pode trazer propriedades além das declaradas.
Use lenient quando:
- os dados ainda estão sendo descobertos;
- a origem envia muitos campos variáveis;
- você declarou apenas o conjunto essencial;
- uma integração madura precisa receber novos campos sem romper o contrato atual.
Lenient não corrige um campo obrigatório ausente nem aceita qualquer conteúdo em uma propriedade declarada. Os tipos conhecidos ainda são normalizados e validados. Esse modo permite campos adicionais.
O que colocar em identifiers
Os dados usados para identificar ou localizar uma pessoa devem ficar em identifiers, não em properties.
Esse bloco recebe tratamento protegido e existe para ajudar o PrismaFlow a reconhecer a pessoa. Exemplos incluem os identificadores adotados pela sua operação, como customer_id, account_id, email, telefone, CPF ou device_id.
Um evento precisa possuir ao menos um identificador.
Nem todo dado pessoal possui a mesma sensibilidade ou a mesma finalidade. O primeiro nome, por exemplo, pode ser necessário para personalizar uma mensagem e costuma fazer mais sentido como trait. Já um CPF, email ou telefone identifica ou permite contatar diretamente a pessoa e precisa da proteção de identifiers.
Antes de colocar um dado pessoal em properties, confirme que ele possui um uso operacional claro e considere que seus valores podem aparecer como amostras no catálogo.
O que colocar em properties
As propriedades descrevem o acontecimento.
Inclua um campo quando ele tiver uso real. Por exemplo, quando ele for necessário para:
- criar um segmento;
- calcular um trait;
- tomar uma decisão em uma jornada;
- personalizar uma ação;
- investigar ou analisar aquele acontecimento.
Quando uma informação descreve a pessoa e precisa continuar disponível além daquele acontecimento — como o primeiro nome usado em uma campanha — ela geralmente deve alimentar um trait. O guia de traits detalhará esse fluxo.
Evite copiar todo o objeto da origem apenas porque ele está disponível. Campos sem uso aumentam o volume, poluem o autocomplete e tornam o contrato mais difícil de entender.
Uma boa definição não é a que possui todos os campos possíveis. É a que possui os campos corretos.
O que é context
O contexto descreve informações gerais do ambiente em que o evento aconteceu.
Em integrações feitas com SDKs de navegador ou aplicativo, ele costuma ser coletado automaticamente. O cliente normalmente não precisa montar esse bloco.
Em integrações server-side, o contexto é opcional e pode ser preenchido manualmente quando houver uma informação ambiental útil.
Não use context como atalho para enviar dados pessoais ou informações centrais do acontecimento. Identificadores pertencem a identifiers. Dados do acontecimento pertencem a properties.
Os caminhos de context também podem aparecer no catálogo de propriedades e nos autocompletes.
Como funciona o catálogo de propriedades
A definição mostra o que deveria chegar. O catálogo mostra o que chegou de verdade nos eventos aceitos.
O catálogo é separado por nome e versão do evento. Para cada caminho observado, ele pode apresentar:
- o tipo encontrado;
- valores de exemplo;
- quando o campo apareceu pela primeira e pela última vez;
- se o caminho faz parte do schema declarado.
Quando um caminho faz parte da definição, o tipo declarado orienta sua normalização e seu uso. Isso evita que um número recebido como "10", por exemplo, permaneça armazenado como texto e produza comparações inesperadas.
Campos aninhados aparecem como caminhos. Dados do contexto aparecem com o prefixo context.*.
Quando ainda não existem observações, a interface pode usar os campos da definição. Quando o catálogo já possui dados, ele alimenta os autocompletes de computed traits, segmentos e jornadas com os caminhos e exemplos recebidos.
O catálogo não substitui o contrato. Um campo aparecer no autocomplete confirma que ele já foi observado, mas não garante que ele chegará em todos os eventos futuros.
Cuidado com dados sensíveis e ruído
O catálogo usa amostras reais dos valores recebidos em properties e context.
Por isso:
- nunca envie senhas, tokens ou segredos nesses blocos;
- mantenha identificadores e dados pessoais sensíveis, como CPF, email e telefone, em
identifiers; - envie outros dados pessoais somente quando houver uma finalidade clara;
- masque valores quando o conteúdo completo não for necessário;
- não envie campos sem uso apenas porque eles existem na origem.
Além do risco de exposição, propriedades desnecessárias criam ruído para quem usa os autocompletes.
Exemplo: um evento de PIX recebido
Neste exemplo, customer_id e account_id ficam protegidos em identifiers. As propriedades guardam apenas dados úteis sobre a transação.
O exemplo não envia o nome da pessoa que originou o PIX porque essa informação não participa dos usos apresentados. Isso é uma decisão deste caso, não uma regra para todos os eventos.
Se uma campanha precisa usar o primeiro nome do próprio cliente, por exemplo, esse dado precisa estar disponível em algum lugar e geralmente será um trait. O cuidado é enviar dados pessoais com uma finalidade definida e dar o tratamento mais protegido aos identificadores e aos dados mais sensíveis.
Exemplo: eventos diferentes para acontecimentos diferentes
Não concentre toda a evolução de um processo em um evento genérico. Acontecimentos separados deixam o uso mais claro.
O recorte abaixo compara a modelagem dos três acontecimentos. Ele não representa o formato de uma requisição de ingestão.
Esse recorte ajuda a montar segmentos e jornadas sobre momentos específicos. Ele também evita propriedades que não terão uso real.
Quando criar uma nova versão
Crie uma nova versão quando a mudança rompe o contrato existente.
Alguns exemplos de mudança incompatível são:
- adicionar uma nova propriedade obrigatória;
- mudar o tipo esperado de uma propriedade;
- passar de
lenientparastrict; - remover um campo que integrações ou automações ainda enviam ou usam.
O PrismaFlow analisa mudanças no schema e avisa quando encontra incompatibilidades conhecidas. Quando a alteração precisa seguir, uma nova versão preserva o contrato anterior.
Preservar a v1 não migra a operação para a v2.
Sua integração precisa começar a enviar version: 2. Segmentos, computed traits e jornadas ligados a nome@v1 também precisam ser avaliados. Uma jornada que escuta apenas a v1 não recebe um evento enviado somente como v2.
Evite novas versões sem necessidade
Versionar costuma ser mais simples no início da integração, quando existem poucas dependências.
Depois de meses em produção, uma versão pode estar conectada a vários segmentos, computed traits e jornadas. Mudar essa comunicação sem coordenar todos os consumidores é arriscado.
Quando a regra de negócio permitir, prefira uma evolução compatível:
- adicione novos campos como opcionais;
- mantenha os campos usados pelas integrações atuais;
- considere
lenientquando a origem precisa enviar propriedades adicionais; - acompanhe o catálogo para descobrir o que está chegando;
- torne obrigatório apenas o que a operação realmente precisa garantir.
Uma nova versão continua sendo a escolha correta para uma mudança realmente incompatível. O cuidado é tratar a migração como uma mudança de integração, não como uma simples edição de formulário.
Checklist para uma boa definição
- O nome descreve um acontecimento claro.
- A versão corresponde ao contrato enviado pela integração.
- Identificadores e dados pessoais sensíveis estão em
identifiers. - Outros dados pessoais possuem uma finalidade clara.
- As propriedades possuem uso real.
- Os tipos declarados representam como os valores devem ser normalizados e usados.
- Os campos essenciais estão declarados e, quando necessário, obrigatórios.
- O modo
strictoulenientfoi escolhido de forma consciente. - Os exemplos do catálogo não expõem dados sensíveis.
- Uma mudança de versão considera todos os consumidores de
nome@versão.