|
| 1 | +--- |
| 2 | +title: "PWA Wrapper Deep Linking" |
| 3 | +url: /refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-deep-linking/ |
| 4 | +weight: 40 |
| 5 | +description: "How to implement deep linking in your PWA Wrapper app to enable inbound and outbound URL handling." |
| 6 | +aliases: |
| 7 | + - /refguide10/mobile/pwa-wrapper/pwa-wrapper-deep-linking/ |
| 8 | +--- |
| 9 | + |
| 10 | +## Introduction |
| 11 | + |
| 12 | +Deep linking enables users to jump directly to specific content in your app via URLs or schemes. PWA Wrapper supports two independent deep linking flows: |
| 13 | + |
| 14 | +* Outbound: your Mendix app opens a URL or deep link (for example, jumping to another app) |
| 15 | +* Inbound: the operating system launches your wrapped app via a registered deep link scheme, and the wrapper routes it into your app content |
| 16 | + |
| 17 | +This guide covers both flows. |
| 18 | + |
| 19 | +## Part 1: Outbound — Opening URLs and Deep Links |
| 20 | + |
| 21 | +Use the **OpenDeepLink** JavaScript action to open external URLs or deep links from your nanoflows: |
| 22 | + |
| 23 | +``` |
| 24 | +OpenDeepLink(url: string): Promise<boolean> |
| 25 | +``` |
| 26 | + |
| 27 | +### Behavior |
| 28 | + |
| 29 | +Behavior works as follows: |
| 30 | + |
| 31 | +* **iOS and Android** — This returns `true` or `false` based on success, and catches errors and returns `false` on failure. |
| 32 | + |
| 33 | +### Important Caveat |
| 34 | + |
| 35 | +On both Android and iOS, the result of `OpenDeepLink` (true/false) indicates only that the call succeeded—not whether the target app could actually handle the link. Always test with the actual target apps you expect to open. |
| 36 | + |
| 37 | +## Part 2: Inbound — Registering Deep Link Schemes and Hosts |
| 38 | + |
| 39 | +Configure deep link schemes and hosts in the PWA Wrapper Builder during the app info step. The builder includes a **Deep Link editor** where you define which schemes and hosts your app should respond to. |
| 40 | + |
| 41 | +### Adding a Deep Link Entry |
| 42 | + |
| 43 | +Each deep link entry requires the following: |
| 44 | + |
| 45 | +* **scheme** (required) — For example `myapp`, `pwa`, or `https`/`http` for universal/app links |
| 46 | +* **host** (required) — Domain or authority to match, for example `example.com` |
| 47 | +* **path** fields (optional, pick one at most): |
| 48 | + * **path** — Exact path to match (for example `/profile`) |
| 49 | + * **pathStartWith** — Path prefix to match (for example `/jump` catches `/jump/profile`) |
| 50 | +* **linkFeature** — Free-text label (metadata only, affects HarmonyOS builds) |
| 51 | +* **platform** — `Android`, `iOS`, `HarmonyOS`, `all`, or unset (unset or `all` applies to every platform) |
| 52 | + |
| 53 | +### Common Deep Link Patterns |
| 54 | + |
| 55 | +Here is an example of a **Custom scheme** (works everywhere, no domain ownership needed): |
| 56 | + |
| 57 | +* scheme: `myapp` |
| 58 | +* host: `example.com` |
| 59 | +* path fields: empty |
| 60 | +* Result: catches `myapp://example.com/...` |
| 61 | + |
| 62 | +Here is an example of a **Universal Link / App Link scheme** (requires domain ownership): |
| 63 | + |
| 64 | +* scheme: `https` |
| 65 | +* host: `yourapp.com` |
| 66 | +* pathStartWith: `/jump` |
| 67 | +* Result: catches `https://yourapp.com/jump/*` from any context that supports it |
| 68 | + |
| 69 | +## Part 3: What the Builder Configures Per Platform |
| 70 | + |
| 71 | +The PWA Wrapper builder automatically registers your configured deep links with the operating system. You do not need to manually edit any native configuration files—the builder handles everything behind the scenes. |
| 72 | + |
| 73 | +## Part 4: Domain Verification Files (Manual Setup Required) |
| 74 | + |
| 75 | +{{% alert color="warning" %}} |
| 76 | +For `https` scheme links (Android App Links and iOS Universal Links), the operating system requires verification files hosted on your own domain. The PWA Wrapper builder does not generate or host these files—you must create and publish them yourself. |
| 77 | + |
| 78 | +Without these verification files, `https` links will open in the browser instead of the app. Android may display a disambiguation dialog; iOS Universal Links will fail silently. |
| 79 | +{{% /alert %}} |
| 80 | + |
| 81 | +### Android: assetlinks.json |
| 82 | + |
| 83 | +Create and host `https://yourdomain.com/.well-known/assetlinks.json` on your web server. The file must meet the following criteria: |
| 84 | + |
| 85 | +* Have a valid JSON |
| 86 | +* Be served with `Content-Type: application/json` |
| 87 | +* Be accessible via `https` only (not `http`) |
| 88 | + |
| 89 | +Here is an example structure: |
| 90 | + |
| 91 | +```json |
| 92 | +[ |
| 93 | + { |
| 94 | + "relation": ["delegate_permission/common.handle_all_urls"], |
| 95 | + "target": { |
| 96 | + "namespace": "android_app", |
| 97 | + "package_name": "com.yourcompany.yourapp", |
| 98 | + "sha256_cert_fingerprints": ["AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78"] |
| 99 | + } |
| 100 | + } |
| 101 | +] |
| 102 | +``` |
| 103 | + |
| 104 | +To find your app's SHA-256 fingerprint, use `jarsigner` or the Android Studio Build Variants panel after signing your APK. |
| 105 | + |
| 106 | +### iOS: apple-app-site-association |
| 107 | + |
| 108 | +Create and host `https://yourdomain.com/.well-known/apple-app-site-association` on your web server. The file must meet the following criteria: |
| 109 | + |
| 110 | +* Have a valid JSON (no `.json` extension in the path) |
| 111 | +* Be served with `Content-Type: application/json` |
| 112 | +* Be accessible via `https` only (not `http`) |
| 113 | + |
| 114 | +Here is an example structure: |
| 115 | + |
| 116 | +```json |
| 117 | +{ |
| 118 | + "applinks": { |
| 119 | + "apps": [], |
| 120 | + "details": [ |
| 121 | + { |
| 122 | + "appID": "TEAM_ID.com.yourcompany.yourapp", |
| 123 | + "paths": ["/jump/*"] |
| 124 | + } |
| 125 | + ] |
| 126 | + } |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +The `appID` format is `TEAM_ID.BUNDLE_ID`. The `paths` array should match the paths you configured in the PWA Wrapper Builder. |
| 131 | + |
| 132 | +### Hosting the Files |
| 133 | + |
| 134 | +The `.well-known` directory must be accessible at the root of your domain via `https`. The two typical approaches are: |
| 135 | + |
| 136 | +* Mendix Cloud — Upload the verification files to your Mendix Cloud environment's static file directory. Refer to [Mendix Cloud documentation](/developerportal/deploy/) for details on serving static files, or contact Mendix Support. |
| 137 | +* Custom Domain or External Hosting — If your Mendix app is behind a reverse proxy or hosted on a custom domain, ensure the `.well-known` directory is properly configured to serve these files at the domain root. |
| 138 | + |
| 139 | +### Testing File Accessibility |
| 140 | + |
| 141 | +Verify your files are correctly hosted: |
| 142 | + |
| 143 | +```bash |
| 144 | +curl -I https://yourdomain.com/.well-known/assetlinks.json |
| 145 | +curl -I https://yourdomain.com/.well-known/apple-app-site-association |
| 146 | +``` |
| 147 | + |
| 148 | +Both should return HTTP 200 with `Content-Type: application/json`. |
| 149 | + |
| 150 | +## Part 5: How Inbound Links Reach Your App Content |
| 151 | + |
| 152 | +Once a deep link is caught by the wrapper, it is routed into your app's runtime. The exact process depends on the platform: |
| 153 | + |
| 154 | +* Android: the wrapper loads the incoming deep link in the webview |
| 155 | +* iOS: The wrapper loads the incoming deep link in the webview |
| 156 | + |
| 157 | +{{% alert color="info" %}} |
| 158 | +One implication of deep links is that your Mendix app's routing (pages, deep-link microflows, etc.) must be configured to handle the deep link URL. |
| 159 | +{{% /alert %}} |
| 160 | + |
| 161 | +## Common Deep Linking Pitfalls |
| 162 | + |
| 163 | +When employing deep linking, watch out for the following pitfalls: |
| 164 | + |
| 165 | +* Missing verification files — Forgetting to create and host `assetlinks.json` (Android) or `apple-app-site-association` (iOS) for `https` scheme links is the most common integration failure. |
| 166 | +* Using https without domain ownership — `https` scheme links require that you own and control the domain; do not use `https` for domains you do not own. |
| 167 | +* Misinterpreting the `OpenDeepLink` return value — The Boolean result only indicates the call succeeded, not whether the target app successfully opened or handled the link. |
| 168 | +* Mismatched path configuration — Ensure your `path` and `pathStartWith` values match the actual Mendix page URLs or `deep-link` microflow entry points your app exposes. |
| 169 | + |
| 170 | +## Read More |
| 171 | + |
| 172 | +* [PWA Wrapper](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/) |
| 173 | +* [PWA Wrapper Capabilities](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/pwa-wrapper-capabilities/) |
| 174 | +* [Build PWA Wrapper Apps](/refguide10/mobile/distributing-mobile-apps/pwa-wrapper/build-pwa-wrapper-apps/) |
0 commit comments