Linked domains

Linking your domain to the app makes the website and the app act like the same thing. Tap a link to your site in Messages or Gmail and it opens in your app instead of the browser. Sign in to your site in a browser and the password autofills the next time the app prompts for it. Apple calls these features Universal Links and Shared Web Credentials, behind a single iOS entitlement called Associated Domains. Google calls them App Links and credential sharing.

#iOS

Add an ios section to config/ruby_native.yml with the same bundle ID and team ID you entered during Apple onboarding in the Ruby Native dashboard:

ios:
  bundle_id: com.example.myapp
  team_id: ABCD123456

That's it. The gem serves /.well-known/apple-app-site-association automatically, and the build pipeline includes the Associated Domains entitlement in every iOS build.

#Android

Add an android section with your application ID and the SHA-256 fingerprint of your app signing key. Find the fingerprint in Play Console under Setup → App integrity → App signing key certificate:

android:
  package: com.example.myapp
  cert_fingerprint: "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"

The gem serves /.well-known/assetlinks.json automatically, and every Android build registers your domain for App Links. Deploy the config change to production, then trigger a build: Android checks the file when the app is installed or updated, so the file needs to be live before users install.

Use the app signing key fingerprint, not the upload key. With Play App Signing, Google signs what users download, so that's the certificate Android verifies against.

#Linking specific paths

By default every URL on your domain opens the app. To link only part of your site, list path prefixes in linked_paths:

linked_paths:
  - /pair/

Links matching a prefix open the app; everything else keeps opening in the browser. Useful when the app covers a slice of the product and your emails link to pages the app doesn't show.

iOS picks the change up on your next deploy (plus Apple's propagation delay below). Android bakes the list into the app at build time, so deploy the config change first, then ship a new build.

#What the user sees

  • They tap a link to your site in another app (Messages, Gmail, Notes, etc.) or scan a QR code with their camera. Your app opens directly to that URL instead of the browser.
  • They sign in once on your website, then install your app. When the app shows a sign-in form, the saved password is offered above the keyboard.

No changes to your Rails app are required for either behavior. The native app handles routing the URL into your existing web views.

#Propagation delay

Apple aggressively caches the apple-app-site-association file via their CDN. After you ship the first build with the entitlement, Apple can take up to 24 hours to fetch and propagate the file. Subsequent changes (adding new domains, etc.) face the same delay.

In practice this means: the very first time a user installs your app from TestFlight or the App Store, linked domains may not work for a few hours. Once Apple has cached the file, everything is instant.

Android has no CDN in the middle. Each device verifies assetlinks.json directly when it installs or updates the app, so a live file plus a fresh install is enough.

#Multiple domains

The gem serves both files at whatever URL your Rails app is running at. If your marketing site is at example.com and your app is at app.example.com, only the latter gets linked. Both Apple and Google look for the file at the exact host.

If you want both domains linked on iOS, the cleanest fix is to serve a copy of the AASA file from your marketing site at example.com/.well-known/apple-app-site-association. The contents can be identical to what the gem serves. On Android the app registers only the host it was built with, so extra domains open in the browser.

#Reference