Deep Linking

Overview

Deep linking allows you to open a specific page within your app from an external source such as a website, email, or SMS. If the app is not installed, users are redirected to the appropriate app store. If on an unsupported platform, users are redirected to a fallback website. This guide covers setup and usage of deep linking across:

Android (App Links)
iOS (Universal Links and URL Schemes)
Push notifications
Emails
In-app messages

To function correctly, deep links must:

Be hosted over HTTPS
Include the required verification files:
- Apple App Site Association
- Asset Link

Android setup
iOS setup

Android setup

Use Android Studio’s App Links Assistant to simplify setup.

Steps:

Open Android Studio → Tools → App Links Assistant
Follow steps to set up links to your site
Android Studio auto-generates the required code and assetlinks.json file

Manifest example:

<activity android:name=".SecondActivity" 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" />
    <data android:host="yoursite.com" />
  </intent-filter>
</activity>

Activity handler example:

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();

The generated assetlinks.json file must be hosted at:

https://yoursite.com/.well-known/assetlinks.json

Apple supports Universal Links and URL Schemes.

When to use:

Universal Links: For email, SMS, and external sources
URL Schemes: For push or in-app links when the app is open

Setup Universal Links:

In Xcode → select target → Signing & Capabilities → add Associated Domains
Add domain as applinks:yourdomain.com

OneSignal’s iOS SDK uses openURL for Launch URL. This redirects to browser first, then back into app.To suppress this:

Use data instead of url in API
Or add OneSignal_suppress_launch_urls to Info.plist as a Boolean with value YES More Info

AppDelegate logic:

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb,
     let webpageURL = userActivity.webpageURL {
    print("Received Universal Link: \(webpageURL)")
  }
  return true
}

Host the `apple-app-site-association` JSON at:

https://your_url/.well-known/apple-app-site-association

Example file:

Placeholder	Replace with
`TEAMID`	Your Apple Team ID (found in Apple Developer account)
`com.example.example`	Your iOS app bundle identifier
`/page-name`	The path(s) in your app that should handle deep links

{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.example.example",
      "paths": ["/page-name", "/page-name/*"]
    }]
  }
}

Hosting the verification files

// Node server example
const http = require('http');
const url = require('url');

http.createServer((req, res) => {
  const path = url.parse(req.url).pathname;
  if (path === '/.well-known/assetlinks.json') {
    res.writeHead(200, {'Content-Type': 'application/json'});
    res.end(JSON.stringify([{
      relation: ["delegate_permission/common.handle_all_urls"],
      target: {
        namespace: "android_app",
        package_name: "com.example.deeplink",
        sha256_cert_fingerprints: ["8A:4C:3D:..."]
      }
    }]));
  } else if (path === '/.well-known/apple-app-site-association') {
    res.writeHead(200, {'Content-Type': 'application/json'});
    res.end(JSON.stringify({
      applinks: {
        apps: [],
        details: [{ appID: "TEAMID.com.example.deeplink", paths: ["*"] }]
      }
    }));
  } else {
    res.writeHead(404);
    res.end('Not Found');
  }
}).listen(3000);

Send with deeplinks

Send push notification with deeplinks
Send email with deep links
Send in-app messages with deep links

Include the deep link as:

url property (Launch URL)
Or data property (recommended for iOS to suppress browser redirect)

Behavior:

Android: Opens to linked activity directly
iOS: Opens browser, then app (unless suppressed with plist flag)

Send email with deep links

By default, email links use OneSignal’s tracking, which alters the URL and breaks deep linking.

To support deep linking:

Disable link tracking in the dashboard (Track link clicks)
Or set disable_email_click_tracking: true in API

Tradeoff:

You lose click metrics in Email Reports

Behavior matrix:

Scenario	Result
iOS + Safari + Universal Link + Tracking Enabled	Opens Safari, asks to open app
iOS + Safari + Universal Link + Tracking Disabled	Opens app directly
iOS + Non-Safari + Universal Link	Opens App Store
Android + Universal Link or App Link	May open App Store if not installed
Android + App Link + Tracking Disabled	Opens app directly
Android + App Link + Tracking Enabled	Opens browser first, then app

Drag-and-drop editor:

Use Custom Action ID
Set deep link URI as Action Name

HTML editor:

Use Click Name

Use event listener:

OneSignal.getInAppMessages().addClickListener(event -> {
  if ("https://your_url_here".equals(event.getResult().getActionId())) {
    // Redirect user
  }
});

FAQ

Why does my iOS deep link open the browser first before opening my app?

OneSignal’s iOS SDK uses openURL for Launch URL, which redirects to the browser first, then back into the app. To suppress this behavior:

Use data instead of url in the API and handle the deep link in your Notification Click Listener
Or add OneSignal_suppress_launch_urls to your Info.plist as a Boolean with value YES

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

Overview

Android setup

Steps:

Manifest example:

Activity handler example:

When to use:

Setup Universal Links:

AppDelegate logic:

Host the `apple-app-site-association` JSON at:

Hosting the verification files

Send with deeplinks

Send email with deep links

To support deep linking:

Behavior matrix:

Drag-and-drop editor:

HTML editor:

Use event listener:

FAQ

Why does my iOS deep link open the browser first before opening my app?

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

​Overview

​Android setup

​Steps:

​Manifest example:

​Activity handler example:

​When to use:

​Setup Universal Links:

​AppDelegate logic:

​Host the apple-app-site-association JSON at:

​Hosting the verification files

​Send with deeplinks

​Send email with deep links

​To support deep linking:

​Behavior matrix:

​Drag-and-drop editor:

​HTML editor:

​Use event listener:

​FAQ

​Why does my iOS deep link open the browser first before opening my app?

Overview

Android setup

Steps:

Manifest example:

Activity handler example:

When to use:

Setup Universal Links:

AppDelegate logic:

Host the `apple-app-site-association` JSON at:

Hosting the verification files

Send with deeplinks

Send email with deep links

To support deep linking:

Behavior matrix:

Drag-and-drop editor:

HTML editor:

Use event listener:

FAQ

Why does my iOS deep link open the browser first before opening my app?