
A deep link in a push notification sends the person who taps it to a specific screen in your app. In Braze you choose the link in the push composer, and your app has to register and route it. This guide covers deep links in push notifications with Braze: which link type to use, what Android and iOS each need, and how to test in the right order.
Key Takeaways
- Custom scheme links are the simpler choice for push, and need no association file when used only from push, in-app messages, Content Cards or Banners.
- On Android, the
com_braze_handle_push_deep_links_automaticallyflag defaults to false, so set it to true inbraze.xml. - On iOS, register the scheme in
Info.plist, add it toLSApplicationQueriesSchemes, then implement the handler. - If your iOS delegate returns false from
shouldOpenURL, you own the routing for that link. - Test every link outside Braze before you build the campaign.
- A push open event does not prove the right screen opened.
What is a deep link in a Braze push notification?
A deep link is a URL that opens a specific screen in your app instead of the home screen. In the push composer, the Braze push message guide says you can prompt customers to open your application, redirect them to a specified web URL, or open a specific page of your application with a deep link.
The composer setting is half the job. Your app registers and routes the link, and that sits with your mobile developers. Agree who owns each half before the brief is written.
Which link type should a push notification use?
Braze's iOS guide describes three ways to handle links from Braze messages in your app. The table compares them.
| Link type | Example | Documented fit | Association file needed |
|---|---|---|---|
| Custom scheme | myapp://products/123 | Push, in-app messages, Content Cards, Banners | No |
| Universal link | https://myapp.com/products/123 | Email, SMS, link-provider channels | Yes |
| Open Web URL Inside App | Any secure web URL | Web page shown in a modal WebView | No |
For push, we'd start with a custom scheme. The iOS deep linking guide says custom schemes are simpler when you only need deep links from push, in-app messages, Banners or Content Cards. It also says you don't need an association file when you only use custom schemes from those channels.
Universal links can still reach the app from push when forwardUniversalLinks is set to true. Choose that route when a link provider already owns your routing, not by default.
What does Android need before a tapped push opens the right screen?
Set the handling flag first. The Braze push deep linking page says the com_braze_handle_push_deep_links_automatically flag defaults to false on Android. Until you set it to true in braze.xml, a tap on a push won't bring your app to the foreground or route to the deep link destination.
In the Flutter example on that page, a push_opened event still reaches the Dart listener even though the flag is off. Open events can look normal while the screen never opens. Check the destination on a device.
For custom routing, Android lets you set one delegate that handles every deep link Braze opens across Content Cards, in-app messages and push notifications. The documentation places it in your app's Application.onCreate(). If you set a custom handler, confirm that your gotoUri implementation handles the link and doesn't drop it.
Cordova needs its own step. By default, the Braze Cordova SDK doesn't automatically handle push deep linking, so you add preferences to config.xml.
What does iOS need before a tapped push opens the right screen?
On iOS the order is scheme, allowlist, then handler. Register your custom scheme in Info.plist, add it to the LSApplicationQueriesSchemes key, and implement the handler. The documentation says links to a screen inside your own app still require that your app's custom scheme be listed in Info.plist.
Apps built with Xcode 27 and later must adopt the UIScene life cycle. iOS then delivers custom scheme URLs to your scene delegate through scene:openURLContexts:. If your app hasn't adopted scenes yet, application:openURL:options: still applies.
Braze calls your delegate's shouldOpenURL implementation before it handles any URL. If you implement it and return false, you handle the link yourself, and Braze neither opens it nor forwards it to your delegate methods. If you don't implement it, the SDK default returns true and Braze opens the URL.
How do you set up deep links in push notifications with Braze?
The order below is ours. It puts the cheap checks before the campaign build, so a routing fault is found before a send is scheduled.
- Agree one link format with the app team: the scheme, the path pattern and the list of screens a push may open.
- Register the scheme and the handler in the app. On Android, set the handling flag to true.
- Test each link outside Braze. On iOS, run
xcrun simctl openurl bootedwith your link. On Android, open the link from another app. - Build the campaign and choose the deep link option in the on-click behaviour.
- Send a test push to a physical device and tap it.
- Read the verbose log for the link before you schedule the send.
Step three is the one teams skip. The Braze documentation tells you to test the deep link outside of Braze first, and to open the URL from another app such as email or a browser.
How do you debug a push deep link that fails?
Follow the investigation path in the Braze deep linking troubleshooting page. Test the link outside Braze, then enable verbose logging and reproduce the issue. The log shows the channel, useWebView and isUniversalLink.
Compare channels when only one fails. If the same deep link works in an in-app message but not from push, the documentation says the issue is likely in your push deep link handling, not in the link itself. On iOS, the same page says to look in shouldOpenURL for conditional logic that may filter links from specific channels.
Two further checks save time. Universal links have limited support in the iOS simulator, so test them on a physical device. And if a campaign uses Open Web URL Inside App and shows a blank page, verify the address is a secure web address, because plain web addresses fail silently in the SDK's WebView.
What does the debugging order look like in practice?
This is a hypothetical example, written to show the order of reasoning. It isn't client work and it reports no result.
Imagine a retailer whose push opens the app but lands on the home screen instead of the basket. The team opens the same link from another app. If it opens the basket there, the scheme and handler are sound, and the fault sits in push handling.
On Android, the handling flag is the first thing to check. On iOS, the team reads the verbose log for the push and checks whether a shouldOpenURL implementation returns false for that channel. Only if the link also fails outside Braze does the team return to the scheme and the handler.
How do deep links in push notifications connect to the rest of the programme?
Deep links sit inside wider mobile work. Our guide to using deep links to drive mobile engagement in Braze covers the destination side, and triggered push notifications in Braze covers the send logic that decides when a link is delivered.
Once the link works, measure it. See how to analyse push notification performance in Braze and A/B testing push notifications in Braze for the reporting and test design. For journeys that mix channels, read using Braze for cross-channel customer journeys, and for pre-send checks see automated campaign QA in Braze.
Link handling is also part of the SDK work behind any mobile programme. One case study on guiding a lean internal team through core SDK and API integration covers how that integration work was shared across several agencies.
What does CustomerIK recommend?
As a Braze implementation partner, CustomerIK recommends treating each deep link as a small release. Give every link an owner, a test on a physical device and a place in the campaign checklist. Don't send a push whose link hasn't opened its screen outside Braze first.
Frequently Asked Questions
1. Why does my push open the app but not the right screen?
On Android, check that the handling flag is set to true, because it defaults to false. On either platform, test the link outside Braze to see whether the fault is in your app's routing.
2. Do I need an association file for deep links in push?
Not if you only use custom scheme deep links from push, in-app messages, Content Cards or Banners. You need one when you use universal links.
3. Can I handle every link myself on iOS?
You can. Implement shouldOpenURL and return false, then handle the URL in that method. Braze won't open it or forward it to your delegate methods.
4. Does a push open event prove the deep link worked?
It doesn't. In the Flutter example in the Braze documentation, the push opened event still reaches the Dart listener when the Android handling flag is off.
5. Should I test deep links in a simulator?
Use one for custom schemes if it helps. For universal links, the troubleshooting page says to test on a physical device.
Sources
- Braze, Deep linking in push notifications for the Braze SDK. Retrieved 07 Nov 2026.
- Braze, iOS deep linking guide. Retrieved 07 Nov 2026.
- Braze, Troubleshoot deep linking. Retrieved 07 Nov 2026.
- Braze, Create a push message. Retrieved 07 Nov 2026.
- These pages describe the Braze SDK and composer as documented on 07 Nov 2026. Check them again before you ship, because defaults and Xcode requirements can change.
- Written by CustomerIK, a Braze implementation partner.
CustomerIK is a Braze implementation partner working across onboarding, technical integration, marketing operations and customer data management.
If your push deep links open the app but not the screen, let's talk.




