Métricas, eventos e cobertura

O Agilink distingue quatro eventos. Um clique é um acesso elegível observado pelo Worker. app_open é uma abertura aceita e relatada pelo aplicativo. content_view é a confirmação de conteúdo realmente exibido pelo aplicativo. legacy_content_load preserva o relato dos binários antigos, que podia acontecer após carregar HTTP e antes de exibir o conteúdo.

Não some esses quatro tipos como pessoas, instalações ou conversões. App Links e Universal Links podem abrir o aplicativo sem passar pelo Worker. Uma visita no navegador, uma abertura nativa e uma confirmação podem pertencer ao mesmo fluxo. Eventos do aplicativo são client_reported; isso descreve sua origem e não comprova identidade, pagamento ou acesso ao conteúdo.

Totais e visitantes

A nova API calcula os totais a partir das linhas de eventos disponíveis, sem somar os contadores diários ou históricos. Esses contadores são preservados separadamente e podem conter informação sem evento individual correspondente. As telas ou relatórios legados podem, portanto, apresentar valores diferentes.

uniqueVisitors conta hashes distintos e não vazios de cliques no conjunto consultado. unknown, independentemente de maiúsculas/espaços, não vira visitante. Um hash é uma estimativa por rede/IP e salt, não um usuário autenticado; mudança de rede ou salt altera a estimativa. Os únicos de dois links, países ou dias não podem ser somados para obter o total global.

identifiedClicks informa quantos cliques têm hash reconhecido. A API não devolve esse hash, IP, cidade, payload bruto ou contexto secreto. Campos ausentes de dispositivo, país e origem são normalizados como unknown. Os eventos nativos atuais não fornecem país, portanto esse filtro normalmente os exclui quando um país específico é escolhido.

Período e agrupamento

O início é inclusivo e o fim exclusivo. Os instantes precisam incluir timezone/offset e admitem precisão de até milissegundos. O timezone da consulta escolhe os buckets de calendário; não muda os instantes enviados. O padrão é America/Sao_Paulo. Séries horárias permitem até 31 dias; as demais consultas, até 366 dias.

As séries são esparsas: retornam apenas buckets com eventos. Um bucket ausente não prova ausência de atividade, pois a coleta pode ter perdas. start do bucket é um instante UTC; localLabel é somente uma legenda. Em mudanças de horário de verão, não assuma que um dia sempre tenha 24 horas ou que a legenda local seja um identificador único.

O grupo é o grupo atual do link. Mover um link de principal para operacional muda o agrupamento de seus eventos antigos. Links removidos não entram nas consultas, que usam os links atuais para preservar o escopo e a classificação. Campanhas, tags e pastas terão seus próprios contratos nos marcos seguintes.

Conteúdo confirmado em 24 horas

A coorte usa as aberturas que ocorreram no período selecionado. Uma abertura é confirmada quando existe content_view do mesmo app, link e openId, referenciando seu evento pai, no intervalo entre a abertura e menos de 24 horas depois. Essa visualização pode ocorrer depois do fim do período consultado.

Por isso, contentViews do período e confirmedOpens24h têm significados diferentes. A taxa é confirmadas/aberturas e é null quando não há aberturas. matureOpens24h informa quantas aberturas já tiveram 24 horas para receber confirmação; as demais são provisórias. Confirmações atrasadas e retentativas podem modificar a taxa. Ela não é taxa de instalação nem mede todas as visualizações possíveis.

Recuperação

O relatório de recuperação conta tokens emitidos e etapas que ainda estão retidos no armazenamento da recuperação por colagem/App Clip. Cada etapa informa número de eventos e número de tokens distintos. Eventos de etapa são filtrados pelo horário em que foram recebidos; emissão usa a criação do token. Uma etapa no período pode pertencer a um token emitido antes dele.

copied, store_choice, clip_preview e page_presented são interações declaradas. recovered significa que o servidor resgatou o contexto; não significa conteúdo exibido ou instalação. Não divida etapas por emissões como uma conversão de coorte. A limpeza de tokens também elimina suas etapas, por isso esse resultado não é um histórico permanente.

Detecção própria e Install Referrer não são somados às etapas de tokens. Seus destinos podem gerar os eventos nativos normais, quando a integração os registra. Ausência de etapas não significa falha dessas alternativas.

Disponibilidade e frescor

As respostas trazem generatedAt, período, filtros e coverage. completenessGuaranteed permanece false: eventos anteriores à implantação, navegação que não passou pelo Worker, falta de rede, limites da fila e limpeza podem impedir reconstruir toda a atividade. producer=legacy_unknown identifica origem anterior sem proveniência suficiente.

Use o guia da API e os sete endpoints para aplicar filtros e paginação. A API administrativa exige autorização; os contratos públicos do SDK têm outra finalidade.