Um cliente esperando por um código experimenta enfileiramento, entrega, leitura e digitação como um único atraso. Separe esses intervalos antes de decidir se um cadastro lento reflete a entrega da mensagem ou o fluxo de verificação como um todo.
Quais timestamps devo coletar?
Colete os eventos do ciclo de vida do Verify por meio de uma assinatura de webhook. Armazene os timestamps do payload.
Os payloads dos eventos identificam estas etapas:
| Evento | Timestamp | O que registra |
|---|---|---|
verify.verification.created | created_at | A verificação foi criada |
verify.attempt.sent | sent_at | Bird entregou um código de verificação a um canal |
verify.attempt.delivered | delivered_at | O canal reportou a entrega |
verify.attempt.undelivered | failed_at | Essa tentativa de código de verificação falhou |
verify.verification.verified | verified_at | O destinatário enviou o código correto |
verify.verification.failed | failed_at | O plano de entrega não conseguiu entregar um código |
Mantenha o tipo de evento junto de cada timestamp. Os dois campos failed_at descrevem escopos diferentes: uma tentativa e o plano de entrega da verificação.
Desduplique entregas usando webhook-id, que identifica um evento e permanece estável entre retentativas. Use o timestamp do payload ao ordenar eventos, porque a ordem de entrega pode mudar.
Qual intervalo responde à minha pergunta?
Use envio-até-entrega para o tempo de entrega reportado. Use criação-até-verificação para o tempo de verificação concluída.
| Intervalo | O que inclui |
|---|---|
created_at até sent_at | Tempo antes de o canal aceitar um código de verificação, potencialmente incluindo falhas anteriores do canal |
sent_at até delivered_at | Processamento após a aceitação do canal e o intervalo de entrega reportado |
created_at até verified_at | A espera completa, incluindo leitura e digitação do código |
Um timestamp de envio nem sempre marca o envio à operadora. Para SMS, o canal de Bird aceita a tentativa antes que o pipeline downstream SMS a envie à operadora.
Relatórios de entrega são indicativos. Operadoras e provedores de e-mail diferem no que confirmam e na velocidade com que reportam.
Compare o mesmo canal e mercado ao longo do tempo. Diferenças entre países podem refletir convenções de relatório, além da velocidade de entrega.
Um evento verified confirma que o código foi recebido e usado. Seu intervalo mede a conclusão, não apenas a entrega da mensagem.
Como parear eventos quando códigos são reenviados?
Agrupe eventos por verification_id, canal e endereço do destinatário. Exclua pares que permaneçam ambíguos.
Os eventos públicos do Verify não contêm identificador de tentativa. Um reenvio ou mudança de canal cria outra tentativa sob o mesmo identificador de verificação.
Um evento sent e seu evento delivered têm valores de webhook-id diferentes. Esse header desduplica eventos. Ele não une as etapas de uma tentativa.
A ordem dos timestamps pode separar sequências simples. Envios repetidos para o mesmo endereço no mesmo canal podem se sobrepor. A ordenação sozinha não prova qual entrega corresponde.
Marque essas amostras como ambíguas em vez de atribuir uma latência precisa de tentativa. O intervalo criação-até-verificação permanece como uma medição separada.
Um canal indisponível ou restrito pode falhar sem um evento sent. Exija sent_at antes de calcular um intervalo envio-até-entrega.
Por que meus números podem diferir do dashboard?
O dashboard pode medir um intervalo diferente. Ele também pode incluir tentativas diferentes do seu relatório de eventos.
O dashboard mede da criação da tentativa até a resolução para tentativas qualificadas, cobradas e entregues. Ele exclui timeouts de entrega corrigidos dessa amostra de latência porque seus tempos de resolução não são entregas medidas.
Sua janela de relatório usa o horário de cobrança. Um relatório baseado em eventos usando o horário de envio pode, portanto, incluir um conjunto diferente de tentativas.
A latência armazenada reflete o estado de entrega quando a cobrança é lida. Uma atualização posterior de entrega pode deixar essa amostra inalterada.
Um percentil é nulo quando não existem amostras qualificadas. Preserve essa distinção em vez de exibir zero, o que implicaria entrega imediata.
Compare a mesma janela de relatório antes de investigar uma discrepância. Use eventos de webhook quando sua aplicação precisar de seu próprio intervalo e agrupamento.
Como devo reportar códigos lentos e ausentes?
Reporte o tempo junto de tentativas não entregues e verificações que não foram concluídas.
Um relatório de latência contendo apenas tentativas entregues omite as pessoas cujos códigos nunca chegaram. Mantenha essas falhas visíveis ao lado do resumo de tempo.
O evento verify.verification.failed cobre planos de entrega esgotados. Expiração e esgotamento de tentativas com código incorreto não emitem esse evento, então ele não é uma contagem completa de não conversão.
Rastreie a criação da verificação e a conclusão bem-sucedida na sua aplicação. Mantenha sessões não resolvidas separadas em vez de atribuir a elas uma duração de entrega inventada.
Divida as tentativas por canal e mercado do destinatário. Quando reportados, carrier e mcc_mnc identificam a rede de processamento. Ambos são nulos para e-mail, WhatsApp e Telegram.
Um failover de canal pode explicar o código atrasado de um cliente. Inspecione a sequência de tentativas antes de tratar todo o atraso como tempo de entrega de um único canal.
Em resumo
Escolha o intervalo que você precisa.
Tempo de entrega reportado e tempo de verificação concluída respondem perguntas diferentes. A conclusão inclui leitura e digitação do código.
Pareie tentativas com cautela.
Os eventos identificam a verificação, mas não cada tentativa. Envios repetidos no mesmo canal podem tornar o pareamento ambíguo.
Mantenha as falhas ao lado do relatório de latência.
Entregas bem-sucedidas sozinhas excluem códigos que nunca chegaram. Reporte entregas não realizadas e verificações incompletas separadamente.
Compare tráfego equivalente.
Relatórios de entrega variam por canal e mercado. Registre seu intervalo e regras de amostragem antes de comparar percentis.