Deep Linking - OneSignal

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

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

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:

{
  "apps": [],
  "details": [
    {
      "appID": "TEAMID.com.example.deeplink",
      "paths": ["*"]
    }
  ]
}

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

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)

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

Track link clicks is disabled.

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
  }
});

On this page

Overview
Send with deeplinks

Overview

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

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

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:

{
  "apps": [],
  "details": [
    {
      "appID": "TEAMID.com.example.deeplink",
      "paths": ["*"]
    }
  ]
}

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

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)

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

Track link clicks is disabled.

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
  }
});

On this page

Overview
Send with deeplinks

​Overview

​Android setup

​Steps:

​Manifest example:

​Activity handler example:

​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:

Release Notes

​Overview

​Android setup

​Steps:

​Manifest example:

​Activity handler example:

​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:

Overview

Android setup

Steps:

Manifest example:

Activity handler example:

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:

Overview

Android setup

Steps:

Manifest example:

Activity handler example:

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: