Este guia orienta você pelos problemas mais comuns de deep linking e deferred deep linking (DDL) que observamos com os Singular Links e como resolvê-los.
Definições rápidas
| Termo | O que significa |
|---|---|
| Deep Link | Abre uma tela ou um conteúdo específico dentro do seu app — só funciona se o app já estiver instalado. |
| Deferred Deep Link (DDL) | Envia um novo usuário primeiro para a App Store ou Play Store e, em seguida, o direciona para uma tela específica na primeira vez que ele abre o app após a instalação. |
| Passthrough ( _p ) | Um parâmetro que transporta dados personalizados através do link até o app. |
| Fallback / Landing Page | Onde os usuários chegam quando o app não pode ser aberto. |
| Social Landing Page | Uma página web exibida antes de redirecionar os usuários para o app ou a loja de apps — comum em campanhas de redes sociais. |
Antes de começar: limitações dos Universal Links (iOS)
Os Universal Links são controlados inteiramente pelo iOS, não pela Singular. Alguns comportamentos simplesmente não podem ser alterados depois que um link é configurado de determinada maneira. Entender isso desde o início economizará seu tempo:
- Se o app estiver instalado, o iOS sempre tentará abri-lo diretamente — nesse caso, as landing pages e as URLs de fallback são ignoradas.
- Esse comportamento não pode ser alterado depois. Um link criado com um deep link não pode ser forçado a enviar os usuários existentes para a App Store.
- O arquivo AASA da Apple (Apple App Site Association) só é atualizado na instalação ou na atualização do app — não instantaneamente e não sob demanda.
- Redirecionamentos quebram os Universal Links. Eles exigem um toque direto – sem envelopamento de links ou redirecionamentos intermediários.
O que isso significa para você:
- Se você precisa de um link que sempre vá para a App Store, ele deve ser criado sem um deep link desde o início.
- Um QR code ativo ou uma campanha que já usa um Universal Link não pode ter esse comportamento alterado de forma confiável.
-
As social landing pages só aparecerão se o app não puder ser aberto.
Problemas comuns e como resolvê-los
Causas prováveis:
- O manipulador de deep links não está totalmente implementado no app
- O app não está lendo o deep link resolvido do Singular SDK
- Os pré-requisitos do DDL não estão totalmente atendidos
O que verificar:
- Teste o deep link diretamente (sem passar pelo Singular link).
-
Confirme que o seu
SingularLinkHandler
está implementado e lendo corretamente:
- getDeeplink()
- isDeferred()
- getPassthrough()
- Verifique se o DDL está habilitado ( should_index_ddl = true ).
Se o deep link funciona quando testado diretamente, mas não através do Singular link, o problema quase sempre está na lógica de navegação do seu app — não no link em si.
No iOS (Universal Links): Isso geralmente significa que a configuração do Universal Link está incompleta. Verifique:
- O Team ID e o iOS App Scheme estão configurados corretamente na Singular
- Os Associated Domains estão adicionados no Xcode
- O arquivo AASA existe e inclui o link ID correto
Dica para builds de dev/QA: Se você estiver testando em um build de dev ou QA, o seu dispositivo pode ainda não ter o arquivo AASA mais recente. Tente reinstalar o app após reiniciar o dispositivo.
No Android: Isso geralmente aponta para intent filters mal configurados. Verifique:
- A impressão digital SHA256 do App Links está configurada corretamente (se estiver usando App Links)
- assetlinks.json está acessível no seu domínio da Singular
- Os intent filters correspondem ao que está configurado na página Singular Apps
Se tudo acima estiver correto e o problema persistir, o problema provavelmente está na lógica do seu manipulador de deep links.
Erro típico: "O Safari não pode abrir a página porque o endereço é inválido."
Por que isso acontece:
- O Safari tem limitações conhecidas ao lidar com certos Universal Links para novos usuários
- _force_redirect=1 está presente no link
Este é um comportamento esperado , e o fluxo deve continuar da seguinte forma: o usuário vê o erro → toca em OK → é solicitado a abrir a App Store.
Causa provável: O parâmetro passthrough ( _p ) não está devidamente anexado ou codificado em URL.
Melhores práticas:
- Sempre codifique os valores JSON em URL antes de adicioná-los ao link
- Leia os dados de passthrough de singularLinkParams.passthrough
Os dados de passthrough estão disponíveis para ambos : deep links e deferred deep links, portanto, se estiverem faltando, o problema quase sempre está na codificação ou na recuperação.
Por que isso acontece: Depois que um Singular link é criado com um deep link, ele sempre tentará abrir o app se estiver instalado. Isso é controlado no nível do SO:
- iOS: regido pelo arquivo AASA
- Android: regido pela associação do certificado SHA256
Não há como substituir isso depois. Se você quer um link que sempre envie os usuários para a loja, ele precisa ser criado sem um deep link desde o início.
Causa raiz: O iCloud Private Relay da Apple está habilitado no dispositivo.
Por que isso quebra o DDL: O Private Relay altera o endereço IP entre o clique e a instalação, de modo que o IP do clique e o IP da instalação não coincidem — o que quebra a atribuição probabilística.
Recomendação:
- Desabilite o iCloud Private Relay durante os testes
- Teste usando o Chrome ou outro navegador que não seja o Safari
Por que isso acontece: O link está configurado com um deep link, que sempre tem prioridade sobre uma landing page quando o app está instalado.
Regra principal: App + Deep Link sempre prevalece sobre uma landing page. Uma social landing page só aparecerá se o app realmente não puder ser aberto.
Causa provável: O tracking link que você está usando para testar está com dupla codificação de URL, tornando-o não resolvível pelo dispositivo ou pela Singular.
Por que isso acontece: Quando um Singular Link contendo parâmetros de deep link (como _dl ou _p ) é copiado de determinados ambientes (por exemplo, Slack, clientes de e-mail ou ferramentas de mensagens), a URL pode ser codificada uma segunda vez. Por exemplo:
- Correto (codificação simples): https://yourapp.sng.link/Xxxxx/yyyy?_dl=myapp%3A%2F%2Fstory&_p=%7B%22story_id%22%3A%22BananaStory%22%7D
- Inválido (dupla codificação): https%3A%2F%2Fyourapp.sng.link%2FXxxxx%2Fyyyy%3F_dl%3Dmyapp%3A%2F%2Fstory%26_p%3D%7B%22story_id%22%3A%22BananaStory%22%7D
Um link com dupla codificação não redirecionará corretamente, e a instalação ou o clique resultantes podem não aparecer nos logs de atribuição da Singular.
O que verificar:
- Sempre copie os tracking links diretamente da página Singular Manage Links — não de uma mensagem do Slack ou de outra ferramenta que possa ter recodificado a URL.
- Verifique se o link começa com https:// (não https%3A%2F%2F ). Se você vir caracteres codificados em porcentagem logo no início da URL, o link inteiro está com dupla codificação.
- Use uma ferramenta de decodificação de URL (por exemplo, urldecoder.org ) para verificar se o link decodifica para um formato de Singular Link válido.
- Decodifique o link uma vez e use a URL resultante para os testes.
Observação: O valor do parâmetro _p (passthrough) ainda deve ser codificado em URL (por exemplo, %7B%22story_id%22%3A%22BananaStory%22%7D para {"story_id":"BananaStory"} ). Apenas a estrutura da URL externa em si não deve ter dupla codificação.
Problema: Os usuários que clicam em um Singular link a partir do navegador Samsung Internet podem ser redirecionados para a Google Play Store — mesmo quando o app já está instalado e o link está configurado corretamente.
O que observamos:
- Google Chrome: o link abre o app conforme esperado
- Samsung Internet: o mesmo link redireciona para a Play Store
Isso pode acontecer tanto se o link for aberto diretamente no Samsung Internet quanto se estiver incorporado em uma página web e clicado a partir dela.
Causa raiz: O Samsung Internet tem uma configuração de privacidade integrada que bloqueia, por padrão, a abertura externa de apps.
- Quando habilitada: o navegador bloqueia o deep link e recorre à Play Store
- Quando desabilitada: o link abre o app corretamente, correspondendo ao comportamento do Chrome
Confirmamos que este é um problema de configuração do navegador, não um problema de configuração da Singular — os Android App Links e as impressões digitais SHA-256 estão configurados corretamente, e o comportamento do link é consistente em todos os lugares quando essa configuração é desativada.
O que isso significa para você: Alguns usuários Samsung podem chegar à Play Store mesmo com o app instalado, dependendo das configurações individuais de privacidade do navegador. Isso não pode ser controlado de forma programática do nosso lado.
Se você quiser orientar os usuários afetados: Você pode informá-los de que o Samsung Internet pode bloquear por padrão os links que abrem apps, e que habilitar "Abrir apps externos" (ou similar) nas configurações de Privacidade do Samsung Internet restaurará a experiência esperada dentro do app.
Por que isso acontece: Quando os usuários clicam em um Singular Link de dentro de certos navegadores in-app de redes sociais, o navegador pode bloquear os Universal Links padrão do iOS ou os App Links do Android. Como resultado, o app pode abrir com sucesso, mas o deep link não é passado para o app, fazendo com que os usuários cheguem à tela inicial padrão em vez do destino pretendido.
Para resolver isso, a Singular oferece a Social Landing Page , uma página de destino intermediária que ajuda a preservar o deep link e a direcionar os usuários de forma confiável ao destino correto dentro do app.
Quais plataformas são compatíveis?
A Social Landing Page é compatível com:
- iOS
- Android (navegadores in-app do Facebook, Facebook Messenger, Facebook Messenger Lite e Instagram)
-
Partner Links, incluindo:
- Facebook Web
- TikTok Ads Web
- X (Twitter) Web
- Snapchat Web
Como habilito a Social Landing Page?
Ao criar ou editar um Singular Link, habilite Landing Page em Social Link Settings .
Esta opção está disponível para:
- Links de Custom Source
- Links de Mobile Web-to-App
- Partner links
Observação: Se o seu link já tiver a iOS Landing Page habilitada, o suporte para Android também é habilitado automaticamente—nenhuma configuração adicional é necessária.
Quando devo usar a Social Landing Page?
Habilite a Social Landing Page sempre que estiver executando campanhas web-to-app por meio de plataformas sociais compatíveis. Ela ajuda a garantir que os usuários sejam direcionados ao conteúdo pretendido dentro do app em vez da tela inicial do app, melhorando a experiência de deep linking e reduzindo os deep links com falha causados pelos navegadores in-app de redes sociais.
Lista de verificação de solução de problemas (tente isto antes de contatar o Suporte)
- [ ] Testou o deep link diretamente, sem passar pela Singular
- [ ] Testou tanto um fluxo de usuário já instalado quanto um fluxo de instalação nova
- [ ] Verificou se o manipulador do SDK está implementado corretamente
- [ ] Confirmou os pré-requisitos de plataforma para iOS e/ou Android
- [ ] Desabilitou o iCloud Private Relay ao testar o DDL no Safari
- [ ] Confirmou que não há envelopamento de links nem encurtador de URL em uso
- [ ] Copiou o tracking link diretamente da página Singular Manage Links (não do Slack, e-mail ou outra ferramenta de mensagens que possa ter dupla codificação da URL)
Ainda precisa de ajuda? Contate o Suporte
Para nos ajudar a investigar o mais rápido possível, inclua:
- O tracking link completo que você usou
- Tipo de dispositivo, versão do SO e navegador
- Se o app estava instalado ou não no momento do clique
- Comportamento esperado vs. comportamento real
- Capturas de tela, se disponíveis
- Uma gravação de tela curta mostrando: o navegador em uso, o clique no link e o comportamento resultante (abertura do app, redirecionamento para a loja, erro, etc.)
Fornecer essas informações antecipadamente nos ajuda a reduzir as idas e vindas e a resolver o problema mais rapidamente.