Deep Links in Push Notifications with Braze: Setup Order

Top-down view of a paper route strip with a green line ending at a phone screen, with a brass compass beside it.

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_automatically flag defaults to false, so set it to true in braze.xml.
  • On iOS, register the scheme in Info.plist, add it to LSApplicationQueriesSchemes, 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 typeExampleDocumented fitAssociation file needed
Custom schememyapp://products/123Push, in-app messages, Content Cards, BannersNo
Universal linkhttps://myapp.com/products/123Email, SMS, link-provider channelsYes
Open Web URL Inside AppAny secure web URLWeb page shown in a modal WebViewNo

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.

  1. Agree one link format with the app team: the scheme, the path pattern and the list of screens a push may open.
  2. Register the scheme and the handler in the app. On Android, set the handling flag to true.
  3. Test each link outside Braze. On iOS, run xcrun simctl openurl booted with your link. On Android, open the link from another app.
  4. Build the campaign and choose the deep link option in the on-click behaviour.
  5. Send a test push to a physical device and tap it.
  6. 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

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.

Preferences

Privacy is important to us, so you have the option of disabling certain types of storage that may not be necessary for the basic functioning of the website. Blocking categories may impact your experience on the website.

Accept all cookies
Accept all cookies

These items are required to enable basic website functionality.

Always active

These items are used to deliver advertising that is more relevant to you and your interests.

These items allow the website to remember choices you make (such as your user name, language, or the region you are in) and provide enhanced, more personal features.

These items help the website operator understand how its website performs, how visitors interact with the site, and whether there may be technical issues.

Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.