> ## Documentation Index > Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt > Use this file to discover all available pages before exploring further. # Deep Linking > Configure deep linking para direcionar usuários de notificações push, emails e mensagens in-app para telas específicas no seu aplicativo Android ou iOS usando Universal Links, App Links ou esquemas de URI personalizados. ## 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](./links). *** ## Pré-requisitos Antes de configurar deep links, você precisa de: * Uma [conta OneSignal](https://dashboard.onesignal.com) com um aplicativo configurado * O [SDK do OneSignal](./mobile-sdk-setup) 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) *** ## Tipos de deep links Existem três mecanismos comuns de deep linking. Cada um tem comportamento diferente dependendo se o aplicativo está instalado. | Tipo | Plataforma | Formato | Aplicativo não instalado | | ---------------------------------- | ------------- | ----------------------------- | -------------------------------------- | | **Universal Links** | iOS 9+ | `https://yourdomain.com/path` | Abre a URL no Safari | | **App Links** | Android 6.0+ | `https://yourdomain.com/path` | Abre a URL no navegador | | **Esquemas de URI personalizados** | iOS e Android | `myapp://path` | Falha 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. *** ## Configuração Android (App Links) Use o [App Links Assistant](https://developer.android.com/training/app-links) 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: ```xml theme={null} ``` ### Tratar o intent recebido ```java theme={null} Intent appLinkIntent = getIntent(); String appLinkAction = appLinkIntent.getAction(); Uri appLinkData = appLinkIntent.getData(); ``` ### Hospedar o arquivo Digital Asset Links 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](https://developer.android.com/training/app-links/verify-android-applinks) para o formato completo do arquivo e as etapas de verificação. *** ## Configuração iOS (Universal Links) Os [Universal Links](https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app) 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](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) 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` ### Tratar o Universal Link no seu aplicativo ```swift Swift theme={null} 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 } ``` ```objectivec Objective-C theme={null} - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *))restorationHandler { if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { NSURL *url = userActivity.webpageURL; // Route to the correct screen based on the URL path return YES; } return NO; } ``` ### 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: ```json theme={null} { "applinks": { "apps": [], "details": [{ "appID": "TEAMID.com.example.app", "paths": ["/path/*", "/another-path"] }] } } ``` Consulte a documentação da Apple [Supporting Associated Domains](https://developer.apple.com/documentation/xcode/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](./mobile-sdk-reference#addclicklistener-push) 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. *** ## Tratar deep links com o SDK do OneSignal 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: ```kotlin Kotlin theme={null} OneSignal.Notifications.addClickListener { event -> val url = event.notification.launchURL val data = event.notification.additionalData // Route to the correct screen based on url or data } ``` ```swift Swift theme={null} class AppDelegate: UIResponder, UIApplicationDelegate, OSNotificationClickListener { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { OneSignal.Notifications.addClickListener(self) return true } func onClick(event: OSNotificationClickEvent) { let url = event.notification.launchURL let data = event.notification.additionalData // Route to the correct screen based on url or data } } ``` ```javascript React Native theme={null} OneSignal.Notifications.addEventListener('click', (event) => { const url = event.notification.launchURL; const data = event.notification.additionalData; // Route to the correct screen based on url or data }); ``` ```dart Flutter theme={null} OneSignal.Notifications.addClickListener((event) { final url = event.notification.launchUrl; final data = event.notification.additionalData; // Route to the correct screen based on url or data }); ``` ```csharp Unity (C#) theme={null} OneSignal.Notifications.Clicked += (sender, e) => { var url = e.Notification.LaunchURL; var data = e.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](./mobile-sdk-reference#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: ```kotlin Kotlin theme={null} OneSignal.InAppMessages.addClickListener { event -> val actionId = event.result.actionId // Route based on the action ID (your deep link URI) } ``` ```swift Swift theme={null} func onClick(event: OSInAppMessageClickEvent) { let actionId = event.result.actionId // Route based on the action ID (your deep link URI) } ``` ```javascript React Native theme={null} OneSignal.InAppMessages.addEventListener('click', (event) => { const actionId = event.result.actionId; // Route based on the action ID (your deep link URI) }); ``` ```dart Flutter theme={null} OneSignal.InAppMessages.addClickListener((event) { final 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](./mobile-sdk-reference#addclicklistener-in-app). *** ## Notificações push Inclua o deep link de uma destas duas formas: | Método | Propriedade da API | Comportamento | | --------------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ | | **Launch URL** | `url` (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) | `data` | A 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](#comportamento-do-launch-url-no-ios) e trate a navegação no click listener) Consulte [URLs, links e deep links](./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. ### Habilitar deep links em email 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**: Adicione o atributo `disable-tracking=true` à tag âncora (`…`) 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](./email-message-reports). Considere usar exclusões de rastreamento por link para preservar análises em URLs que não são deep links. ### Comportamento de deep links em email | Cenário | Resultado | | --------------------------------------------------------- | ------------------------------------------------------ | | iOS + Safari + Universal Link + Rastreamento desabilitado | Abre o aplicativo diretamente | | iOS + Safari + Universal Link + Rastreamento habilitado | Abre o Safari, pergunta para abrir o aplicativo | | iOS + cliente de email não-Safari + Universal Link | Abre a App Store se o aplicativo não estiver instalado | | Android + App Link + Rastreamento desabilitado | Abre o aplicativo diretamente | | Android + App Link + Rastreamento habilitado | Abre 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](./iam-click-actions#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`](./in-app-message-api#click-name) 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](#click-listener-de-mensagem-in-app) para interceptar a ação e navegar o usuário no seu aplicativo. *** ## Testar deep links ### Android Use `adb` para testar App Links sem enviar uma notificação: ```bash theme={null} 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: ```bash theme={null} curl -I https://yourdomain.com/.well-known/assetlinks.json ``` ### iOS Use a [ferramenta de validação de Associated Domains](https://search.developer.apple.com/appsearch-validation-tool/) 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 ### Deep link iOS abre o Safari em vez do aplicativo 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](#comportamento-do-launch-url-no-ios) * **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. ### Deep link Android abre o navegador * **`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. ### Deep link funciona no push, mas não no email O rastreamento de cliques de email reescreve URLs, quebrando a verificação de domínio. [Desabilite o rastreamento de cliques](#habilitar-deep-links-em-email) para emails que contêm deep links. ### Deep link recebido, mas o aplicativo não navega * 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. ### Posso personalizar deep links com dados do usuário? Sim. Use [URLs Dinâmicas](./links#dynamic-urls) 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}}`. ### Posso usar deep links com esquemas de URI personalizados? 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. ### Deep links funcionam com o OneSignal Journeys? 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. *** Launch URLs, parâmetros UTM, URLs dinâmicas e configuração de rastreamento de links. Referência completa da API para click listeners e tratamento de eventos de notificação. Configure ações de clique para botões e elementos de mensagens in-app. Configuração de notificações push específica por plataforma para Android e iOS.