Skip to main content

Module 2 — Prerequisites

Deep links require two pieces of OS-level configuration. These are platform requirements (not SDK calls) and cannot be done from code. Get them right first — most "the link does nothing" problems live here (Layer 1 in the overview).

Decide your scheme, domain, and path vocabulary first. See Decide three things before you start. The examples below use yourapp and link.paylisher.com — replace them with your own.

1. Register a custom URL scheme​

In your target's Info.plist, declare the scheme your links use (replace yourapp):

<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>yourapp</string>
        </array>
    </dict>
</array>

Without this, yourapp://... links never open your app.

Universal Links open your app directly from an https:// URL — no "Open in app?" prompt. They have an app side and a server side.

a. App side — Associated Domains​

In Xcode → Target → Signing & Capabilities → Associated Domains, add:

applinks:link.paylisher.com

This writes the entitlement:

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:link.paylisher.com</string>
</array>

b. Server side — the association file​

Apple fetches an apple-app-site-association (AASA) file from https://link.paylisher.com/.well-known/apple-app-site-association. It must list your app's appID (TEAMID.com.yourcompany.yourapp) and the allowed paths:

{
  "applinks": {
    "details": [
      {
        "appID": "ABCDE12345.com.yourcompany.yourapp",
        "paths": ["/home*", "/products*", "/wallet*", "/profile*"]
      }
    ]
  }
}
  • link.paylisher.com is the production link domain for all Paylisher short/Universal links — send your Team ID and Bundle ID to Paylisher so your appID is added to the hosted file (it's a merge, not an overwrite).
  • Using a custom branded domain? Add it to both the Associated Domains entitlement and the dashboard; Paylisher hosts the association file for it. If you host it yourself, serve it with Content-Type: application/json and no redirects.

iOS fetches the AASA file at install time. After it changes (or your appID is added), delete and reinstall the app to refresh it.

You can. Start with the custom scheme (step 1) only, get routing working, then add Universal Links later. Everything from SDK setup onward is identical either way.

Next: Module 3 — SDK setup →