Skip to main content

iOS - Universal Links Setup Guide

For Q2 partners and Financial Institutions (FIs) who need to enable Universal Links for their iOS Q2 Mobile banking application.

Overview​

Universal 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 Universal Links for your domain or domains.

Q2 handles the technical implementation, including:

  • managing the Apple App Site Association configuration as part of app and domain setup
  • adding or updating the Apple App Site Association file for supported domains
  • configuring the app to work with the supported Associated Domains setup used by the FI app

You only need to provide the information outlined below.

For the built-in Q2MobileApp Universal Link contract and route format, see Deep Linking.

For Q2DevApp setup and local testing prerequisites, see Setup DevApp.

What You Need to Provide to Q2​

To set up Universal Links for your domain, please provide the following information:

1. Domain Information (Required)​

Provide the fully qualified domain or domains where Universal Links should be enabled.

Examples:

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

2. App Association Information (Required)​

Provide the app identifier Q2 should associate with the domain.

This typically includes:

  • the iOS app ID for the FI app
  • the app bundle ID associated with that app ID

Example app ID:

  • 3MW532H43Y.com.firstbancorp.MobileBanking

3. Path Behavior Preference (Required)​

Choose one of the following options:

Option A: All Supported Paths Open in App​

All supported links for the configured domain open in the app by default.

Choose this if: You want standard online banking links to open in the mobile app whenever possible.

Option B: Path-Based Exclusions​

Specific URL paths can be excluded from opening in the app so they remain in the browser, while all other supported paths continue to open in the app.

Choose this if: You have OAuth flows, Plaid flows, third-party integrations, or web-only pages that should not launch the app.

If choosing Option B, also provide:

  • the paths that should stay in the browser
  • any additional exclusions needed for OAuth, Plaid, or other third-party flows
  • whether you need anything other than the default case-insensitive behavior

How It Works​

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

1. Associated Domains​

The app must include the Associated Domains entitlement for the supported domain:

applinks:{domain}

This allows iOS to treat links from that domain as candidates for opening in the app.

2. Apple App Site Association File​

Q2 adds or updates the Apple App Site Association file that verifies the relationship between your domain and the app. This file is hosted at:

https://{domain}/.well-known/apple-app-site-association

Example:

https://online.yourbank.com/.well-known/apple-app-site-association

For built-in Q2MobileApp Universal Links, the host must match universalAndAppLinkAssociatedDomain, and the link path must still satisfy the runtime contract documented in Deep Linking.

Apple App Site Association File​

Below is an example Apple App Site Association file. Final values vary by FI domain, app ID, and required path behavior.

{
  "applinks": {
    "details": [
      {
        "appIDs": ["TEAMID.com.q2.mobilr"],
        "components": [
          {
            "/": "*/sdk/plaid_authorize*",
            "exclude": true,
            "comment": "Matches any URL that contains /sdk/plaid_authorize"
          },
          {
            "/": "*/sdk/oauth*",
            "exclude": true,
            "comment": "Matches any URL that contains /sdk/oauth"
          },
          {
            "/": "*",
            "comment": "Match online banking path"
          }
        ],
        "defaults": {
          "caseSensitive": false
        }
      }
    ]
  }
}

Path Exclusions and Rule Behavior​

Path-based exclusions are useful when some links should stay in the browser rather than opening the app.

Common examples:

  • OAuth authorization paths
  • Plaid authorization paths
  • third-party integration paths
  • web-only flows that should not leave Safari

With the example above:

Stays in browser:

  • https://online.yourbank.com/digitalbanking/sdk/oauth/authorize
  • https://online.yourbank.com/digitalbanking/sdk/plaid_authorize

Can open in app:

  • https://online.yourbank.com/digitalbanking/uux.aspx#/accounts
  • https://online.yourbank.com/digitalbanking/uux.aspx#/transfers/new

If you need special include-only behavior or more advanced path matching, describe that to Q2 when requesting setup.

Testing and Validation​

Validate the Apple App Site Association File​

Open the AASA URL directly and confirm it is reachable:

https://{domain}/.well-known/apple-app-site-association

Validate the following:

  • the file is reachable over HTTPS
  • the app ID matches the intended FI app
  • expected exclusions are present
  • supported paths are represented correctly

Validate Associated Domains​

Confirm the app includes the Associated Domains entitlement for the domain:

applinks:{domain}

Test On Device​

Use a real device when validating production Universal Link behavior.

Test the following:

  • a normal online banking link that should open the app
  • an excluded path that should remain in the browser
  • an authenticated flow
  • an unauthenticated flow, if your app defers navigation until after login

For route behavior after the app opens, validate the runtime contract separately in Deep Linking.

Setup Checklist​

Before contacting Q2 to set up Universal Links, ensure you have:

  • domain or domains where Universal Links should be enabled
  • app ID or bundle ID to associate with the domain
  • decision: all supported paths open in app, or path-based exclusions
  • if using exclusions: list of paths that should stay in browser
  • if using exclusions: any OAuth, Plaid, or web-only paths that need special handling

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 Apple App Site Association file myself?​

No. Q2 manages the Apple App Site Association configuration as part of app and domain setup for supported Universal Link domains.

Can excluded paths be updated later?​

Yes. If your path requirements change, provide the updated path list to Q2 so the Apple App Site Association configuration can be updated.

What if I have multiple domains?​

Provide all supported domains in your initial request. Each supported domain needs its own Apple App Site Association file at the standard /.well-known location.

No. This page covers setup and ownership. The accepted built-in Universal Link shape, route rules, and runtime handling are documented in Deep Linking.

Need Help?​

If you are unsure which paths should stay in browser or how your Universal Links should behave, open a support ticket on q2developer.com or contact your Q2 representative.