Rails Universal Link Fails to Launch iOS App When Triggered via Button

Below is some guidance related to universal links that might help you troubleshoot your issue:

Verify Your Associated Domains Setup

Universal links require that your iOS app includes an Associated Domains Entitlement configured with your website’s domain. Double‑check that:

• Your app’s entitlements include the proper associated domain (for example, "applinks:yourdomain.com").
• The apple-app-site-association file is served from your website at either https://yourdomain.com/.well-known/apple-app-site-association or https://yourdomain.com/apple-app-site-association, with the correct content type (typically application/json) and content.

If these settings are not correct or the entitlement does not match the file’s content, iOS won’t trigger your app.

Use a Fully‑Qualified URL in Your Link

When testing universal links, the link must be an absolute URL that matches one of the domains in your entitlement. In your example you are linking to a relative path ("/ios_app"). Since universal links require a matching URL (e.g., https://yourdomain.com/ios_app), the link should be:

HTMLCopied
<a href="https://yourdomain.com/ios_app" class="btn btn-primary">Open in App</a>

Using a fully‑qualified URL ensures that iOS processes the click as a universal link.

Behavior in Web Views vs. Safari

Keep in mind that universal links are intended to work when tapped in Safari or other apps that use system‑provided browsers. They might not work as expected in an embedded web view. For example, if your website is loaded inside an in‑app web view or if you perform a javascript redirect, the system might not trigger the app.

Your current approach in ios_app.html.erb uses a JavaScript redirect:

ERBCopied
<script>
    window.location = "https://apps.apple.com/br/app/laager-meu-consumo/id1234387091"
</script>

This may work as a fallback when the app isn’t installed, but it isn’t the same as having a universal link that directly launches your app. The system only intercepts a universal link when it’s a top‑level navigation.

Is Universal Links the Correct Approach?

Yes, universal links are the proper method to launch your iOS app from your website. Just be sure that:

• The URL in your link is a fully‑qualified URL that exactly matches one of the paths you declared in your apple-app-site-association file.
• Your iOS app is installed and correctly configured.
• You’re testing on a real device using Safari (or another system‑provided app), as universal link behavior may differ in local file views or non‑Safari browsers.

Summary

1. Make sure your app includes the Associated Domains Entitlement with the correct domain.
2. Ensure your apple-app-site-association file is correctly formatted, served at the right URL, and has the required MIME type.
3. Use a fully‑qualified universal link (https://yourdomain.com/ios_app) in your button/link.
4. Test in an appropriate Safari session, not just through a redirect on a local file or in an embedded web view.

Following these steps should help ensure that your universal link triggers the app as expected when the user taps the button on your site.