Skip to content

Commit b7b5340

Browse files
UrazAkgultanUrazAkgultan
committed
Add PWA Wrapper deep linking guide
1 parent 0ab4a69 commit b7b5340

3 files changed

Lines changed: 173 additions & 0 deletions

File tree

‎content/en/docs/refguide/mobile/pwa-wrapper/_index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ This PWA Wrapper documentation section includes the following topics:
2929
* Signing reference: [Sign PWA Wrapper Apps](/refguide/mobile/pwa-wrapper/sign-pwa-wrapper-apps/) explains the signing step in the build flow
3030
* Capabilities guide: [PWA Wrapper Capabilities](/refguide/mobile/pwa-wrapper/pwa-wrapper-capabilities/)
3131
* Limitations: [PWA Wrapper Limitations](/refguide/mobile/pwa-wrapper/pwa-wrapper-limitations/)
32+
* Deep linking guide: [PWA Wrapper Deep Linking](/refguide/mobile/pwa-wrapper/pwa-wrapper-deep-linking/) explains how to handle inbound and outbound deep links
3233

3334
## Typical Use Cases
3435

‎content/en/docs/refguide/mobile/pwa-wrapper/pwa-wrapper-deep-linking.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
---
2+
title: "PWA Wrapper Deep Linking"
3+
url: /refguide/mobile/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+
---
7+
8+
## Introduction
9+
10+
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:
11+
12+
* **Outbound** — your Mendix app opens a URL or deep link (e.g., jumping to another app)
13+
* **Inbound** — the operating system launches your wrapped app via a registered deep link scheme, and the wrapper routes it into your app content
14+
15+
This guide covers both flows.
16+
17+
## Part 1: Outbound — Opening URLs and Deep Links
18+
19+
Use the **OpenDeepLink** JavaScript action to open external URLs or deep links from your nanoflows:
20+
21+
```
22+
OpenDeepLink(url: string): Promise<boolean>
23+
```
24+
25+
### Behavior
26+
27+
**iOS and Android:** Returns `true` or `false` based on success. Catches errors and returns `false` on failure.
28+
29+
### Important Caveat
30+
31+
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.
32+
33+
## Part 2: Inbound — Registering Deep Link Schemes and Hosts
34+
35+
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.
36+
37+
### Adding a Deep Link Entry
38+
39+
Each deep link entry requires:
40+
41+
* **scheme** (required) — e.g., `myapp`, `pwa`, or `https`/`http` for universal/app links
42+
* **host** (required) — domain or authority to match, e.g., `example.com`
43+
* **path** fields (optional, pick at most one):
44+
* **path** — exact path to match (e.g., `/profile`)
45+
* **pathStartWith** — path prefix to match (e.g., `/jump` catches `/jump/profile`)
46+
* **linkFeature** — free-text label (metadata only, affects HarmonyOS builds)
47+
* **platform** — `Android`, `iOS`, `HarmonyOS`, `all`, or unset (unset or `all` applies to every platform)
48+
49+
### Common Deep Link Patterns
50+
51+
**Custom scheme (works everywhere, no domain ownership needed):**
52+
53+
* scheme: `myapp`
54+
* host: `example.com`
55+
* path fields: empty
56+
* Result: catches `myapp://example.com/...`
57+
58+
**Universal Link / App Link (requires domain ownership):**
59+
60+
* scheme: `https`
61+
* host: `yourapp.com`
62+
* pathStartWith: `/jump`
63+
* Result: catches `https://yourapp.com/jump/*` from any context that supports it
64+
65+
## Part 3: What the Builder Configures Per Platform
66+
67+
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.
68+
69+
## Part 4: Domain Verification Files (Manual Setup Required)
70+
71+
{{% alert color="warning" %}}
72+
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.
73+
74+
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.
75+
{{% /alert %}}
76+
77+
### Android: assetlinks.json
78+
79+
Create and host `https://yourdomain.com/.well-known/assetlinks.json` on your web server. The file must be:
80+
81+
* Valid JSON
82+
* Served with `Content-Type: application/json`
83+
* Accessible via `https` only (not `http`)
84+
85+
**Example structure:**
86+
87+
```json
88+
[
89+
{
90+
"relation": ["delegate_permission/common.handle_all_urls"],
91+
"target": {
92+
"namespace": "android_app",
93+
"package_name": "com.yourcompany.yourapp",
94+
"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"]
95+
}
96+
}
97+
]
98+
```
99+
100+
To find your app's SHA-256 fingerprint, use `jarsigner` or the Android Studio Build Variants panel after signing your APK.
101+
102+
### iOS: apple-app-site-association
103+
104+
Create and host `https://yourdomain.com/.well-known/apple-app-site-association` on your web server. The file must be:
105+
106+
* Valid JSON (no `.json` extension in the path)
107+
* Served with `Content-Type: application/json`
108+
* Accessible via `https` only (not `http`)
109+
110+
**Example structure:**
111+
112+
```json
113+
{
114+
"applinks": {
115+
"apps": [],
116+
"details": [
117+
{
118+
"appID": "TEAM_ID.com.yourcompany.yourapp",
119+
"paths": ["/jump/*"]
120+
}
121+
]
122+
}
123+
}
124+
```
125+
126+
The `appID` format is `TEAM_ID.BUNDLE_ID`. The `paths` array should match the paths you configured in the PWA Wrapper Builder.
127+
128+
### Hosting the Files
129+
130+
The `.well-known` directory must be accessible at the root of your domain via `https`. The typical approach is:
131+
132+
* **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.
133+
* **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.
134+
135+
### Testing File Accessibility
136+
137+
Verify your files are correctly hosted:
138+
139+
```bash
140+
curl -I https://yourdomain.com/.well-known/assetlinks.json
141+
curl -I https://yourdomain.com/.well-known/apple-app-site-association
142+
```
143+
144+
Both should return HTTP 200 with `Content-Type: application/json`.
145+
146+
## Part 5: How Inbound Links Reach Your App Content
147+
148+
Once a deep link is caught by the wrapper, it is routed into your app's runtime. The exact process depends on the platform:
149+
150+
**Android:**
151+
152+
The wrapper loads the incoming deep link in the webview.
153+
154+
**iOS:**
155+
156+
The wrapper loads the incoming deep link in the webview.
157+
158+
**Implication for your app:** Your Mendix app's routing (pages, deep-link microflows, etc.) must be configured to handle the deep link URL.
159+
160+
## Common Deep Linking Pitfalls
161+
162+
* **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.
163+
* **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.
164+
* **Misinterpreting the OpenDeepLink return value** — the boolean result only indicates the call succeeded, not whether the target app successfully opened or handled the link.
165+
* **Mismatched path configuration** — ensure your `path` and `pathStartWith` values match the actual Mendix page URLs or deep-link microflow entry points your app exposes.
166+
167+
## Read More
168+
169+
* [PWA Wrapper](/refguide/mobile/pwa-wrapper/)
170+
* [PWA Wrapper Capabilities](/refguide/mobile/pwa-wrapper/pwa-wrapper-capabilities/)
171+
* [Build PWA Wrapper Apps](/refguide/mobile/pwa-wrapper/build-pwa-wrapper-apps/)

‎content/en/docs/refguide/mobile/using-mobile-capabilities/push-notifications/notif-pwa-wrapper.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -220,3 +220,4 @@ When testing, verify behavior on physical Android and iOS devices to ensure noti
220220
* [PWA Wrapper](/refguide/mobile/pwa-wrapper/)
221221
* [PWA Wrapper Capabilities](/refguide/mobile/pwa-wrapper/pwa-wrapper-capabilities/)
222222
* [PWA Wrapper Limitations](/refguide/mobile/pwa-wrapper/pwa-wrapper-limitations/)
223+
* [PWA Wrapper Deep Linking](/refguide/mobile/pwa-wrapper/pwa-wrapper-deep-linking/)

0 commit comments

Comments
 (0)