--- title: Resolução, telemetria, recuperação e associação description: Contratos existentes do SDK e Worker, bases corretas, validade e fronteiras de confiança. --- O SDK usa interfaces públicas já existentes, separadas de `/platform/v1`. O `appId` público define escopo e não é uma credencial. Não inclua chave administrativa, segredo de Worker ou token Cloudflare no aplicativo. A API base é fixa na integração; o hostname público precisa estar na lista exata de hosts autorizados. Uma URL recebida não escolhe outro servidor. [Endpoints e exemplos](/sdk/endpoints-publicos/) · [OpenAPI público](/contratos-publicos/) · [Integração Flutter](/sdk/flutter/). A4a acrescenta disponibilidade e regras de destino na configuração dos links, preservando o schema canônico v1. Links pausados, ainda não iniciados ou expirados deixam de entregar conteúdo pela resolução v1 (404). UTMs explícitas entram nos parâmetros; regra compatível pode selecionar destino web. O contexto observado e a propagação estão descritos em [organização e ciclo de vida](/produto/organizacao/). Não reutilize uma resolução em cache indefinidamente para decidir disponibilidade. ## Resolver um link `GET /v1/links/{id}?appId=...` devolve `{version:1,link:...}`. O ID é `hostname~-prefixo~-slug`, com prefixo vazio permitido. A URL pública aceita um ou dois segmentos; o SDK valida host, caminhos, codificação e comprimento. `appPath` é a rota interna relativa e não a URL pública. Campos públicos incluem título, descrição, imagem, destino web, parâmetros e indicação webOnly; proprietário, tokens e campos internos não são devolvidos. A resolução confirma aplicativo, domínio e disponibilidade atuais; outro app ou link indisponível retorna `404 not_found`. Entradas inválidas retornam `400 invalid_argument`; falha de dependência ou documento incompatível retorna `503 unavailable`. O cliente trata timeout, rede, limite de corpo e versão desconhecida, e recusa redirects da API. A resolução não registra clique nem autentica acesso ao conteúdo privado. Query recebida permanece separada dos parâmetros publicados. Ela não substitui app, host, API ou autorização. Scheme direto legado é opt-in e produz apenas directPath. O envelope `meuapp://agilink/open?v=1&url=` resolve a URL HTTPS interna. Não transforme qualquer URI recebida em uma chamada de rede. ## Enviar eventos nativos `POST /v1/events` recebe `{version:1,appId,events:[...]}`, até 20 itens e 32 KiB por lote. Cada item informa eventId/openId UUID v4, tipo app_open ou content_view, linkId, occurredAt, plataforma ios/android e entryMethod. Os métodos suportados são https, scheme_envelope, explicit_clipboard e app_clip; Install Referrer permanece classificado como https. O collector aceita somente as cinco UTMs, com até 200 caracteres cada. `content_view` exige parentEventId da abertura do mesmo app/link/openId; app_open deve omitir esse campo. O servidor atribui proprietário/produtor, verifica link público ativo e permite horário até sete dias atrás ou cinco minutos à frente. O limite é 600 novos eventos por aplicativo/minuto. Não envie IP, identidade de usuário/instalação, segredo, cidade, fingerprint ou URI completa. HTTP `200` contém ACK por item: accepted, duplicate, retry ou rejected. O formato externo inválido recebe `400`; corpo excessivo, `413`. Um item inválido não impede o processamento dos demais válidos. Reenvie eventos temporários com o mesmo ID, payload, horário e vínculo ao pai; se o pai não chegou, o ACK é retry/parent_missing. Conflito de payload ou de tipo para a mesma abertura é definitivo. O SDK respeita retryAfterSeconds e Retry-After quando aplicáveis. A fila do SDK é persistida, limitada a mil eventos/sete dias e usa lotes de até 20. Persistir na fila não é receber ACK. Falta prolongada de rede, encerramento antes de persistir e limites podem causar perdas. `client_reported` não é prova de instalação ou identidade. `legacy_content_load` pertence à compatibilidade dos binários antigos; não é um novo tipo permitido no lote público. ## Recuperar por colagem ou App Clip A página usa `https:///_agilink/recover/`; a API JSON usa preview, redeem e stage na base fixa. O token transitório tem 256 bits e sete dias de validade. Apenas seu hash é armazenado; tratá-lo como capacidade sensível, sem colocá-lo em logs, analytics ou mensagens. O caminho reservado deve ser tratado pelo provider de recuperação antes do parser normal de links. Preview consulta o contexto sem consumir o claim do app completo. Redeem exige claimId UUID v4 persistido antes da rede: a mesma tentativa recebe o mesmo contexto; outra tentativa recebe `409 already_used`. Preview/redeem permitem até 60 leituras por token/minuto. Os erros distinguem not_found/unavailable_link (404), expired (410), already_used (409), rate_limited (429) e invalid_argument (400). O cliente preserva a tentativa em timeout ou resposta incerta. Stage aceita eventId UUID v4 e page_presented, copied, store_choice ou clip_preview. Um `200 {accepted:false}` pode representar rejeição ou repetição; não o trate como instalação confirmada. São armazenadas até 30 etapas por token; repetir o eventId não adiciona outra etapa. O servidor registra recovered no resgate. A emissão de token (`/v1/recovery/issue`) é interna e autenticada pelo Worker; não pertence ao poder do cliente. No app, mostrar conteúdo real e autorizado precede confirmar content_view. Somente depois da persistência bem-sucedida dessa confirmação, conclua a tentativa de colagem. App Clip depende de assinatura, domínio, associação e App Group próprios; preview, contexto compartilhado ou teste de schema não provam abertura/transferência em aparelho. ## Detecção própria opcional no iOS A integração de produto usa o hostname público: `/_agilink/recovery/detection/challenge`, click, intent, attempt e claim. O SDK usa challenge/attempt/claim; a página do produto captura click e a intenção explícita de instalar. Essas chamadas exigem configuração de domínio habilitada e sdkReady, são limitadas a 4 KiB, aceitam JSON e recusam Origin diferente do próprio domínio quando enviado. O challenge dura dois minutos. A janela de correlação e os recibos de claim são de até 30 minutos. O Worker fixa hostname e IP observados; esses campos enviados pelo cliente não determinam a origem. O protocolo pode devolver no_match, ambiguous, candidate ou confirm_candidate. Apenas candidato elegível pode ser reivindicado; confirmação é exigida pelo modo do domínio. Recibo/attemptId são preservados na retomada. Um candidato pode deixar de ser válido por disputa, expiração, revogação da configuração ou indisponibilidade do link. Os sinais são observações de plataforma, família do dispositivo, versão do sistema, idioma/timezone e contexto de tela/preferências, conforme o schema. Correlação não estabelece identidade e deve se abster em ambiguidades. O SDK exige confirmação por padrão; abertura automática depende do opt-in no domínio e no app. Links explícitos e recuperação escolhida pelo usuário têm prioridade. As rotas correspondentes `/v1/recovery/detection/*` na Edge são **internas**, autenticadas pelo Worker. Não chame essas rotas diretamente nem armazene seu segredo no SDK. O provider experimental/shadow e suas rotas de laboratório são separados e não são apresentados como API pública de integração. ## Associar o domínio ao aplicativo Android consulta `/.well-known/assetlinks.json`. iOS consulta `/.well-known/apple-app-site-association` ou seu alias `/apple-app-site-association`. GET/HEAD são servidos sem redirecionamento, com cache de associação de 300 segundos; HEAD tem corpo vazio. Uma configuração ausente pode produzir lista de associação vazia. Falha de configuração/KV retorna 503 sem cache de sucesso. Salve pacote e certificado Android e identidade iOS corretos, com prefixos autorizados. Os caminhos nativos e o prefixo da aplicação web são independentes. O sistema operacional pode abrir o app antes de consultar a página; webOnly não revoga uma associação já declarada. Para web garantida, use host/caminho fora do escopo nativo. Salvar, publicar no KV, servir AASA/assetlinks e abrir um aparelho são verificações diferentes. O app ainda precisa autorizar o conteúdo e conhecer suas rotas. Os [diagnósticos e receitas Flutter](/sdk/flutter/) ajudam a identificar em qual etapa o fluxo parou.