Pular para o conteúdo principal

​
Visão geral

Deep linking direciona usuários para uma tela específica no seu aplicativo quando eles tocam em um link — seja a partir de um email, SMS, site, notificação push ou mensagem in-app. Se o aplicativo não estiver instalado, o sistema operacional pode redirecionar os usuários para a loja de aplicativos ou para uma página web de fallback. Este guia cobre:
  • Tipos de deep links e quando usar cada um
  • Configuração de plataforma para Android e iOS
  • Tratamento de deep links no seu aplicativo com o SDK do OneSignal
  • Comportamento por canal para push, email e mensagens in-app
Para configuração geral de URLs e links (Launch URLs, parâmetros UTM, URLs dinâmicas, rastreamento de links), consulte URLs, links e deep links.

​
Pré-requisitos

Antes de configurar deep links, você precisa de:
  • Uma conta OneSignal com um aplicativo configurado
  • O SDK do OneSignal instalado no seu aplicativo mobile
  • Um domínio que você controla, hospedado via HTTPS, para Universal Links ou App Links
  • Acesso ao código-fonte e à configuração de build do seu aplicativo (Xcode para iOS, Android Studio para Android)
Existem três mecanismos comuns de deep linking. Cada um tem comportamento diferente dependendo se o aplicativo está instalado.
TipoPlataformaFormatoAplicativo não instalado
Universal LinksiOS 9+https://yourdomain.com/pathAbre a URL no Safari
App LinksAndroid 6.0+https://yourdomain.com/pathAbre a URL no navegador
Esquemas de URI personalizadosiOS e Androidmyapp://pathFalha silenciosamente ou exibe um erro
Recomendação: Use Universal Links (iOS) e App Links (Android) para a experiência mais confiável. Eles usam URLs https:// padrão, funcionam em todos os canais (push, email, SMS) e fornecem comportamento de fallback quando o aplicativo não está instalado. Esquemas de URI personalizados (myapp://) são mais simples de configurar, mas não fornecem comportamento de fallback e podem não funcionar em todos os contextos (por exemplo, clientes de email).
Universal Links e App Links exigem a hospedagem de um arquivo de verificação no seu domínio. Sem esse arquivo, o SO trata o link como uma URL web comum.
Use o App Links Assistant do Android Studio para gerar a configuração necessária.

​
Configurar filtros de intent

Adicione um filtro de intent à Activity que deve tratar o deep link: 
<activity android:name=".DeepLinkActivity" android:exported="true">
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" android:host="yourdomain.com" />
  </intent-filter>
</activity>

​
Tratar o intent recebido

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();
Gere o arquivo assetlinks.json usando o App Links Assistant do Android Studio e hospede-o em: 
https://yourdomain.com/.well-known/assetlinks.json
Consulte a documentação do Google Verify App Links para o formato completo do arquivo e as etapas de verificação.
Os Universal Links da Apple abrem seu aplicativo quando o usuário toca em uma URL https:// correspondente. Para casos de uso mais simples onde o aplicativo está garantidamente instalado, você pode usar URL Schemes em vez disso.

​
Habilitar Associated Domains

  1. No Xcode, selecione seu target → Signing & Capabilities → adicione Associated Domains
  2. Adicione seu domínio: applinks:yourdomain.com
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
    return false
  }
  // Route to the correct screen based on the URL path
  return true
}

​
Hospedar o arquivo Apple App Site Association

Crie um arquivo apple-app-site-association (AASA) e hospede-o em: 
https://yourdomain.com/.well-known/apple-app-site-association
Substitua TEAMID pelo seu Apple Team ID e com.example.app pelo identificador do seu bundle: 
{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.example.app",
      "paths": ["/path/*", "/another-path"]
    }]
  }
}
Consulte a documentação da Apple Supporting Associated Domains para a especificação completa.

​
Comportamento do Launch URL no iOS

O SDK iOS do OneSignal usa openURL para tratar o Launch URL (propriedade url). Isso faz com que o link abra primeiro no navegador e depois redirecione de volta ao aplicativo — o que pode resultar em uma experiência ruim para o usuário. Para evitar isso, use uma destas abordagens:
  1. Use data em vez de url no payload da API e trate o deep link no seu Push Notification Click Listener
  2. Suprima Launch URLs adicionando OneSignal_suppress_launch_urls ao seu Info.plist como um Boolean com valor YES e, em seguida, trate toda a navegação no click listener
A abordagem 1 (usar data + click listener) é recomendada porque oferece controle total sobre a navegação sem depender do SO para resolver a URL.
A maneira mais confiável de tratar deep links de mensagens do OneSignal é usar os click listeners do SDK em vez de depender da resolução de links no nível do SO. Isso oferece controle total sobre a navegação no seu aplicativo.

​
Click listener de notificação push

Use addClickListener para interceptar cliques em notificações e direcionar o usuário com base na URL do deep link ou em dados adicionais: 
OneSignal.Notifications.addClickListener { event ->
  val url = event.notification.launchURL
  val data = event.notification.additionalData
  // Route to the correct screen based on url or data
}
Para a referência completa da API, incluindo Java, Objective-C e Cordova/Ionic, consulte addClickListener() Push.

​
Click listener de mensagem in-app

Use o click listener de mensagem in-app para tratar deep links de botões e ações de mensagens in-app: 
OneSignal.InAppMessages.addClickListener { event ->
  val actionId = event.result.actionId
  // Route based on the action ID (your deep link URI)
}
Para a referência completa da API, consulte addClickListener() In-App.

​
Notificações push

Inclua o deep link de uma destas duas formas:
MétodoPropriedade da APIComportamento
Launch URLurl (ou app_url somente para mobile)O SO abre a URL diretamente. No iOS, isso abre o navegador primeiro, a menos que seja suprimido.
Additional Data (recomendado)dataA URL é passada para o seu click listener. Você controla a navegação inteiramente.

​
Comportamento por plataforma

  • Android: Abre a Activity correspondente diretamente via App Links
  • iOS: Abre o Safari e depois o aplicativo (a menos que você suprima Launch URLs e trate a navegação no click listener)
Consulte URLs, links e deep links para detalhes sobre url, web_url e app_url.

​
Emails

Por padrão, o OneSignal reescreve links de email para rastreamento de cliques. Isso altera a URL, o que quebra o deep linking porque o SO não reconhece mais o domínio como correspondente ao Associated Domain do seu aplicativo. Para preservar deep links, desabilite o rastreamento de cliques usando um destes métodos:
  • Dashboard: Desmarque Track link clicks no editor de email
  • API: Defina disable_email_click_tracking: true
  • Por link: Use o filtro Liquid {{ 'https://yourdomain.com/path' | do_not_track_link }} para desabilitar o rastreamento em links individuais enquanto mantém o rastreamento habilitado para os demais
Editor de email do OneSignal com a caixa de seleção Track link clicks desmarcada
Desabilitar o rastreamento de cliques significa que você perde métricas de cliques nos Relatórios de Email. Considere usar exclusões de rastreamento por link para preservar análises em URLs que não são deep links.
CenárioResultado
iOS + Safari + Universal Link + Rastreamento desabilitadoAbre o aplicativo diretamente
iOS + Safari + Universal Link + Rastreamento habilitadoAbre o Safari, pergunta para abrir o aplicativo
iOS + cliente de email não-Safari + Universal LinkAbre a App Store se o aplicativo não estiver instalado
Android + App Link + Rastreamento desabilitadoAbre o aplicativo diretamente
Android + App Link + Rastreamento habilitadoAbre o navegador primeiro, depois o aplicativo

​
Mensagens in-app

Deep links em mensagens in-app usam o padrão de click listener. Você define um identificador de ação personalizado no editor de mensagens e depois o trata no código do seu aplicativo.

​
Editor drag-and-drop

  1. Adicione um botão ou elemento clicável
  2. Defina a ação de clique como Custom Action ID
  3. Insira o URI do seu deep link como Action Name (ex.: https://yourdomain.com/promo ou myapp://promo)

​
Editor HTML

Use o método openUrl na In-App JS Library para acionar deep links a partir de HTML personalizado.

​
Tratar o clique

Use o click listener de mensagem in-app para interceptar a ação e navegar o usuário no seu aplicativo.

​
Android

Use adb para testar App Links sem enviar uma notificação: 
adb shell am start -a android.intent.action.VIEW \
  -d "https://yourdomain.com/path" \
  com.your.package
Verifique se o seu assetlinks.json está acessível: 
curl -I https://yourdomain.com/.well-known/assetlinks.json

​
iOS

Use a ferramenta de validação de Associated Domains da Apple para verificar o seu arquivo AASA. Você também pode testar Universal Links:
  1. Colando o link no aplicativo Notas
  2. Pressionando o link por mais tempo para confirmar que a opção “Abrir em [App]” aparece
  3. Tocando no link para verificar se ele abre o seu aplicativo
Universal Links não funcionam quando digitados diretamente na barra de endereços do Safari — eles precisam ser tocados a partir de outro aplicativo (Notas, Mail, Mensagens, etc.).

​
Mensagens de teste do OneSignal

  1. Envie um push de teste pelo dashboard do OneSignal com uma URL de deep link como Launch URL ou em Additional Data
  2. Verifique se a notificação abre a tela correta no seu aplicativo
  3. Confira os logs do seu click listener para confirmar que a URL ou os dados foram recebidos

​
Resolução de problemas

Este é o problema mais comum. Possíveis causas:
  • Arquivo AASA não hospedado corretamente — Verifique se está em https://yourdomain.com/.well-known/apple-app-site-association com Content-Type: application/json e sem redirecionamentos
  • Associated Domains não configurado — Verifique no Xcode → Signing & Capabilities → Associated Domains se inclui applinks:yourdomain.com
  • Comportamento do Launch URL — O SDK iOS do OneSignal usa openURL para a propriedade url, o que aciona o comportamento de abertura no navegador primeiro. Use data + click listener ou suprima Launch URLs
  • Testando no Safari — Universal Links não são ativados pela barra de endereços do Safari. Teste a partir do aplicativo Notas, Mail ou outro aplicativo.
  • autoVerify ausente — Certifique-se de que o filtro de intent inclui android:autoVerify="true"
  • assetlinks.json não encontrado — Verifique se o arquivo está em https://yourdomain.com/.well-known/assetlinks.json e retorna HTTP 200
  • Incompatibilidade de fingerprint SHA256 — O fingerprint em assetlinks.json deve corresponder ao certificado de assinatura do seu aplicativo. Builds de debug e release usam certificados diferentes.
O rastreamento de cliques de email reescreve URLs, quebrando a verificação de domínio. Desabilite o rastreamento de cliques para emails que contêm deep links.
  • Verifique se o seu click listener está registrado no início do ciclo de vida do aplicativo (ex.: em Application.onCreate() ou AppDelegate.didFinishLaunchingWithOptions)
  • Verifique se a URL ou o ID de ação corresponde ao que a sua lógica de roteamento espera
  • No iOS, confirme que você não está dependendo de url sem suprimir Launch URLs — o navegador pode consumir o link antes do seu listener ser acionado

​
Perguntas frequentes

​
O que acontece se o aplicativo não estiver instalado?

Com Universal Links (iOS), a URL abre no Safari como uma página web comum. Com App Links (Android), a URL abre no navegador padrão. Em ambos os casos, você pode configurar sua página web para redirecionar para a loja de aplicativos apropriada. Esquemas de URI personalizados (myapp://) falham silenciosamente ou exibem um erro se o aplicativo não estiver instalado.

​
Devo usar Launch URL ou Additional Data para deep linking?

Additional Data (data) é recomendado para deep links mobile porque oferece controle total sobre a navegação via click listener. Launch URL (url) é mais simples, mas tem limitações no iOS (redirecionamento pelo navegador) e não permite lógica de roteamento personalizada. Sim. Use URLs Dinâmicas com sintaxe Liquid para injetar propriedades do usuário, tags ou dados personalizados nas URLs dos seus deep links. Por exemplo: https://yourdomain.com/profile/{{subscription.external_id}}. Sim. Defina o seu esquema personalizado (ex.: myapp://screen) como valor de Launch URL ou Additional Data. Esquemas personalizados funcionam bem para push e mensagens in-app, mas podem não funcionar em clientes de email. Eles também não fornecem fallback se o aplicativo não estiver instalado. Sim. Ao configurar uma etapa de mensagem em um Journey, defina o Launch URL ou Additional Data com o seu deep link. O comportamento é o mesmo que em um push ou mensagem in-app avulsos.

URLs, links e deep links

Launch URLs, parâmetros UTM, URLs dinâmicas e configuração de rastreamento de links.

Referência do SDK mobile

Referência completa da API para click listeners e tratamento de eventos de notificação.

Ações de clique In-App

Configure ações de clique para botões e elementos de mensagens in-app.

Configuração de push mobile

Configuração de notificações push específica por plataforma para Android e iOS.