Configure Universal Links, Android App Links, and the optional web credential associations needed for HTTPS OAuth callbacks.
Before you start
You need a public HTTPS domain that your mobile app is allowed to claim, plus the app's existing URI scheme, iOS bundle identifier, Android package name, and Apple Team ID. In a linked project, Mach reads most of those values from mach.config.json before it asks questions. When Mach Web Hosting is configured, it can also present the stable project.getmach.dev address and verified Production customer domains automatically.
The command flags are intentional overrides. Their precedence is higher than deep link config, profile values, root config, and Expo inference, so use a flag when you need a one-off environment or CI value.
1. Run the setup flow
For most apps, the public URL is the only required value. On a linked Mach Web Hosting project, setup lets the developer choose the stable Production Mach address, an active Production customer domain, or a manual URL. It never suggests Staging or immutable preview addresses because a native app needs a durable host. Mach writes compact deep link configuration and generates the Apple and Android association files. If the linked project uses a Mach-managed Android keystore, setup reads its public SHA-256 signing fingerprint automatically, then offers an optional Google Play App Signing field. Before Google Play enrollment the Mach value is correct for builds Mach signs directly; after enrollment, paste the Play value as an additional fingerprint.
mach deeplink setup
# Select Mach Production, an active customer domain, or enter a manual URL
One source of truth
mach.config.json remains the only Mach deep-link configuration file. Mach does not create a second deep-link JSON source or duplicate identifier values that already exist in the project config.
2. Enable web credentials when your OAuth flow needs them
Universal Links alone are not enough for every HTTPS OAuth callback. When the iOS app uses a browser-based HTTPS callback, choose Enable iOS Web Credentials for HTTPS OAuth callbacks during setup. Mach adds the webcredentials association to the iOS configuration and the Apple association file.
For Android website password and passkey sharing, choose Enable Android Login Credentials for website password and passkey sharing. This adds the Android login credential relation to assetlinks.json.
Generated deep link settings
{
"deepLinks": {
"baseUrl": "https://app.example.com",
"ios": {
"webCredentials": true
},
"android": {
"loginCredentials": true
},
"web": {
"outputDir": "public"
}
}
}
3. Host the association files on the same domain
Deploy the generated files at the root of the exact HTTPS domain. iOS checks the Apple App Site Association file and Android checks assetlinks.json before either platform trusts the claimed link. With Mach Web Hosting, mach web deploy automatically includes the generated association files in the static release, even if the web exporter writes a different output directory.
https://app.example.com/.well-known/apple-app-site-association
https://app.example.com/apple-app-site-association
https://app.example.com/.well-known/assetlinks.json
4. Apply the app configuration
For Expo, Mach prefers the packaged @radhya/mach/expo-plugin and setup offers to install and configure it. Static app config files are updated automatically; custom dynamic config files receive the exact plugin entry when they cannot be safely changed.
For bare React Native, Mach deliberately does not mutate Android XML or Xcode project files in this phase. It reports any missing Android manifest or iOS entitlement entries so you can apply the native change with full control.
5. Verify locally and against the live domain
Verify after the files are deployed, then create a new native build to carry the associated-domain or App Link changes into the app.
mach deeplink verify
mach deeplink verify --live
mach build --platform ios --profile production
