SDK Flutter, confirmação e diagnóstico

Configure AgilinkClient com API HTTPS fixa, appId público e lista exata de hosts. Inicialize o binding cedo e mantenha uma fonte/receiver por aplicativo. Assine receiver.events antes de await receiver.start(). Descarte o receiver apenas ao encerrar seu proprietário; ele não fecha um cliente HTTP compartilhado. Não coloque credencial administrativa no cliente.

O receiver distingue received, resolved, discarded e failed, e mantém uma sequência monotônica. Um link novo vence a resposta tardia de um link anterior. Guarde o destino e seu openContext enquanto login/navegação não estiverem prontos. Uma resolução pública não autoriza um orçamento, usuário ou produto privado: faça essa verificação no seu backend de conteúdo.

Retry e cancelamento

var ignoredThrough = 0;
final subscription = receiver.events.listen((event) {
  if (event.sequence <= ignoredThrough) return;
  // Atualize loading/destino/erro da aplicação para esta sequência.
});
await receiver.start();
// Ação de tentar novamente: conserva contexto e IDs.
await receiver.retry();
// Ação de cancelar: limpe também destino e contexto locais.
ignoredThrough = receiver.discardCurrentOpening();
// Ao encerrar o proprietário:
await subscription.cancel();
await receiver.dispose();

O descarte invalida respostas em andamento e solicita descartar Install Referrer. Uma tentativa persistida de colagem deve ser descartada com deferred.discard() quando o usuário a abandonar. Não reabra um destino cancelado a partir de evento já enfileirado.

Confirmar conteúdo

Com AgilinkAnalytics configurado, confirme somente o contexto do conteúdo que está efetivamente exibido e autorizado. Não confirme ao resolver HTTP, abrir login, apresentar erro ou encaminhar para web.

try {
  await analytics.confirmContentView(destination.openContext!);
  // Se este destino veio do provider de colagem configurado:
  await deferred.complete(destination.openContext!.openId);
} catch (error) {
  // Mantenha a tentativa e ofereça retry sem bloquear a interface.
}

Esse trecho pressupõe conteúdo já exibido, contexto não nulo e provider de colagem presente quando aplicável. A confirmação preserva o primeiro horário e os IDs nas retomadas; falha de persistência não deve consumir a recuperação. Na Play, o provider conclui a tentativa somente depois de salvar a métrica. ACK de entrega continua sendo responsabilidade da fila.

Escolher os providers

Install Referrer é uma opção Android para instalação pela Google Play. O envelope usa agilink_v=1 e agilink_url com URL HTTPS pública codificada; preserva UTM e resolve pela API pública. Não contém appPath, token de recuperação ou segredo. O receiver habilita a opção explicitamente. Não conte instalação como visualização.

Colagem usa ação explícita, token transitório e claim persistido. App Clip usa o mesmo fluxo de token e requer provisionamento próprio. A detecção de produto no iOS tem opt-in separado, é conservadora em ambiguidades e exige confirmação por padrão. Não combine o provider experimental de laboratório com o de produto no mesmo receiver.

Diagnóstico em ordem

1. Resolver manualmente o link na API pública confirma formato, app e disponibilidade, sem testar associação no sistema operacional.
2. Consultar AASA/assetlinks confirma o documento servido; confira package/bundle, certificado e prefixo.
3. Instalar um aplicativo assinado e abrir um HTTPS no aparelho confirma associação real. Scheme manual não substitui esse teste.
4. Conferir o receiver e a autorização do conteúdo verifica navegação/login, prioridade e descarte.
5. Conferir a fila, os ACKs por evento e o relatório administrativo verifica o registro de abertura e conteúdo. Um zero no relatório não identifica sozinho qual etapa falhou.

Timeout, rede, 429 e 5xx pedem retry conforme o intervalo, com IDs preservados. Redirect da API, corpo excessivo, versão não suportada e resposta incompatível não devem cair silenciosamente em fixture. webFallback precisa ser tratado pela aplicação; não relance a mesma URL associada, evitando loop de abertura.

A homologação A3c valida schemas e compatibilidade automatizada. Ela não declara teste físico de Android/iOS, instalação por loja ou App Clip. Os detalhes HTTP estão em contratos públicos e seus exemplos.