Campos

Campos de evento são os atributos definidos no tipo de evento que formam o contrato de dados aceito em POST /events.

Em termos práticos, são esses campos que determinam o que será validado no envio, o que será ignorado e o que poderá ser usado para gerar métricas e monitoramentos.

O que pode ser configurado em um campo

Ao cadastrar um campo no painel de administração, você define:

  • ID do campo: identificador usado no payload da API;
  • nome e descrição: rótulos exibidos no painel;
  • tipo de dado: formato esperado para o valor;
  • tipo de propriedade: como o campo será tratado na modelagem;
  • obrigatoriedade: se o campo precisa estar presente em todo evento;
  • status: se o campo está ativo ou inativo.

Tipos de dado disponíveis

A plataforma permite os seguintes tipos de campo:

  • texto;
  • lista (valores predefinidos);
  • inteiro;
  • decimal;
  • número com casas decimais;
  • booleano.

Observações importantes

  • Campo de texto aceita até 128 caracteres.
  • Campos do tipo lista permitem cadastrar itens permitidos para validação.
  • Em campos decimais, precisão e escala são definidas na criação.

Tipo de propriedade: dimensão ou medição

Cada campo também recebe um tipo de propriedade:

  • dimensão: representa uma característica do evento usada para segmentação;
  • medição: representa um valor variável usado em consolidações.

Essa escolha impacta como métricas e monitoramentos podem ser configurados depois.

Regras de validação no envio de eventos

No recebimento de eventos via POST /events, o contrato de campos é aplicado com as seguintes regras:

  • campos obrigatórios ausentes causam rejeição;
  • valores fora do tipo esperado causam rejeição;
  • campos inativos podem continuar no payload, mas seus valores são ignorados;
  • campos desconhecidos podem ser ignorados ou rejeitados, conforme a configuração do tipo de evento.

Boas práticas para modelar campos

  • Defina IDs estáveis e semânticos desde o início.
  • Comece com um conjunto enxuto de campos essenciais.
  • Use campos de lista quando houver conjunto controlado de valores.
  • Evite criar campos redundantes para o mesmo conceito.
  • Revise periodicamente campos sem uso.

Restrições e ciclo de vida

Algumas configurações são estruturais e devem ser planejadas no momento da criação:

  • o ID do campo não pode ser alterado após cadastro;
  • o tipo de propriedade não pode ser alterado após cadastro;
  • em campos decimais, precisão e escala ficam fixas após criação;
  • itens de campo do tipo lista são gerenciados após o campo ser criado;
  • o tipo de evento possui limite de até 100 campos.

Ao remover um campo, a operação pode falhar se ele estiver em uso por métricas (por exemplo, em dimensões ou agregações).