Android - App Links Setup Guide

For Q2 partners and Financial Institutions (FIs) who need to enable app links for their Android Q2 Mobile banking application.

Overview

Android App Links allow your mobile banking app to open automatically when users tap links to your domain, providing a seamless transition from web to app. This guide explains what information Q2 needs from you to configure app links for your domain(s).

Q2 handles all technical implementation, including:

• Adding your domain(s) to our build configuration
• Generating the correct intent filters in the app manifest
• Creating and hosting the required assetlinks.json Digital Asset Links file

You only need to provide the information outlined below.

What You Need to Provide to Q2

To set up app links for your domain, please provide the following information:

1. Domain Information (Required)

Provide the fully qualified domain(s) where app links should be enabled.

Examples:

• https://banking.yourbank.com
• https://mobile.yourcu.org

Important: Q2 needs this information before the app build so we can add your domain to our build tool. This ensures the correct intent filter is included in the app manifest.

2. Dynamic App Links Preference (Required)

Choose one of the following options:

Option A: All Links Open in App (Default)

All links to your domain will open in the app by default. This is the simplest setup and works for most use cases.

Choose this if: You want all links to your domain to open directly in the mobile app.

Option B: Path-Based Exclusions (Android 15+)

Specific URL paths can be excluded from opening in the app (they'll open in the browser instead), while all other links open in the app.

Choose this if: You have certain pages that should always open in the browser (e.g., OAuth flows, third-party integrations, web-only features).

If choosing Option B, also provide:

1. Paths to EXCLUDE (open in browser):

   • List specific URL paths that should NOT open the app
   • Use wildcards (*) at the end to match all sub-paths and query parameters

   Example exclusions:

   /digitalbanking/sdk/oauth*
   /digitalbanking/sdk/plaid_authorize*
   /public/enrollment*

2. Paths to INCLUDE (open in app):

   • By default, all other paths open in the app
   • Only specify if you need explicit inclusion rules for specific paths

   Example inclusions (optional):

   /digitalbanking/dashboard
   /accounts/*
   /transfers/*

How It Works

Technical Components

When you provide the information above, Q2 configures two key components:

1. Intent Filter (Manifest)

Q2 adds your domain to our build tool, which automatically generates an intent filter in the app's AndroidManifest.xml:

<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" android:host="banking.yourbank.com" />
</intent-filter>

This tells Android that your app can handle links to your domain.

2. Digital Asset Links File (assetlinks.json)

Q2 creates and hosts a Digital Asset Links file that verifies the connection between your domain and the app. This file is hosted at:

https://your-domain/.well-known/assetlinks.json

For basic app links (Option A), the file looks like:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourbank.mobile",
      "sha256_cert_fingerprints": [
        "XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX"
      ]
    }
  }
]

For dynamic app links with exclusions (Option B), Q2 adds a dynamic_app_link_components section:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourbank.mobile",
      "sha256_cert_fingerprints": [
        "XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX"
      ]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {
        "dynamic_app_link_components": [
          { "/": "/digitalbanking/sdk/plaid_authorize*", "exclude": true },
          { "/": "/digitalbanking/sdk/oauth*", "exclude": true },
          { "/": "*" }
        ]
      }
    }
  }
]

Understanding Dynamic App Links (Option B)

If you choose path-based exclusions, here's how the rule evaluation works:

Rule Evaluation Order

1. Order matters - Rules are evaluated top-to-bottom
2. First match wins - Once a rule matches, evaluation stops
3. Wildcards - * at the end of a path matches any sub-paths and query parameters

Example: The path /digitalbanking/sdk/oauth* matches:

• /digitalbanking/sdk/oauth
• /digitalbanking/sdk/oauth/authorize
• /digitalbanking/sdk/oauth/authorize?client_id=123&state=abc

Best Practices for Exclusion Rules

1. List exclusions first - Most specific paths at the top
2. End with a catch-all - { "/": "*" } ensures all other paths open in the app
3. Use wildcards wisely - They match everything after the specified prefix

Example configuration:

"dynamic_app_link_components": [
  { "/": "/oauth*", "exclude": true },          // Exclude OAuth flows
  { "/": "/external/*", "exclude": true },      // Exclude external integrations
  { "/": "/digitalbanking/dashboard" },         // Explicitly include (optional)
  { "/": "*" }                                   // Catch-all: everything else opens in app
]

What URLs Will Do

With the example above:

Opens in BROWSER:

• https://banking.yourbank.com/oauth/authorize
• https://banking.yourbank.com/external/plaid

Opens in APP:

• https://banking.yourbank.com/digitalbanking/dashboard
• https://banking.yourbank.com/accounts
• https://banking.yourbank.com/transfers/new?amount=100

Testing & Validation

Validating the Digital Asset Links File

After Q2 configures your app links, you can validate the setup using Google's Digital Asset Links API:

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://banking.yourbank.com&relation=delegate_permission/common.handle_all_urls

Expected result: The API should return your app's package name and fingerprint, confirming the domain-to-app association is valid.

Note: This validator only checks the basic relationship structure. It does not evaluate dynamic_app_link_components exclusion logic.

Testing on Device

Use ADB commands to simulate tapping links and verify behavior:

Test an excluded link (should open in browser):

adb shell am start -W -a android.intent.action.VIEW \
  -d "https://banking.yourbank.com/oauth/authorize"

Test an included link (should open in app):

adb shell am start -W -a android.intent.action.VIEW \
  -d "https://banking.yourbank.com/accounts" com.yourbank.mobile

Troubleshooting Commands (Android 15+)

If app links aren't working as expected:

Reset app link state:

adb shell pm set-app-links --package com.yourbank.mobile 0 all

Force re-verification:

adb shell pm verify-app-links --re-verify com.yourbank.mobile

Check current app link status:

adb shell pm get-app-links com.yourbank.mobile

Setup Checklist

Before contacting Q2 to set up app links, ensure you have:

• Domain(s) where app links should be enabled
• Decision: All links in app (Option A) or path-based exclusions (Option B)
• If Option B: List of paths to exclude (with wildcards if needed)
• If Option B: List of paths to explicitly include (optional)

To request setup, provide this information to your Q2 contact or open a ticket through q2developer.com.

Frequently Asked Questions

Do I need to host the assetlinks.json file?

No. Q2 creates and hosts this file for you. You don't need to upload or manage any files on your domain.

How long does setup take?

Once you provide the required information, Q2 will configure the domain in our build tool and generate the necessary files. The app will need to be rebuilt with these changes.

Can I update exclusion paths later?

Yes. Create a new support ticket through q2developer.com with the updated path list, and we'll update the assetlinks.json configuration.

What if I have multiple domains?

Provide all domains in your initial request. Each domain will be added to the build configuration and will have its own assetlinks.json file.

Does this work on older Android versions?

Basic app links (Option A) work on Android 6.0 (API 23) and higher. Dynamic app links with exclusions (Option B) require Android 15 (API 35) or higher. On older devices with Option B configured, all links will open in the app by default.

---

Need Help?

If you're unsure which paths to exclude or how to structure your exclusion rules, please open a support ticket on q2developer.com. We can help translate your requirements into the correct configuration.