Setting Up Deep Linking in Angular with AWS Amplify Hosting
Navigating the Challenges of Deep Linking in Angular with AWS Amplify Hosting
Published Jan 17, 2025
Hello Devs,
As a developer, we always been in situation where the previous developer has long moved on, and you’re left with no documentation or answers. That was exactly the situation I found myself in when I started working on an Angular project that required deep linking for both iOS and Android. The previous developer wasn’t available, and I had to figure out how to make deep linking work in the existing codebase. Even after so many years of experience deep linking concept was new to me ( how it works ).
I’ll be honest — it wasn’t a smooth start. One of standup my team raised concern about this So I took this challenge to solve Though I good in Amplify hosting and Angular but how deep links work was exploration part. But with the help of Amazon Q Developer and a lot of trial and error, I eventually managed to set everything up. Amazon Q developer become best buddy to solve issue which I am not aware. I do use ChatGPT but for most of AWS related query used Amazon Q developer because expertise it has.
Image not found
Before diving into the technical steps, let’s take a moment to understand deep linking. You’ve probably seen it many times when using social media apps. For example, in Instagram, WhatsApp, or Facebook, when you want to share a post or a specific piece of content, you usually find a “Share” button or an option to "Copy Link." When you tap it, you're not just sharing a URL; you’re sharing a direct link to that specific content within the app.
This is exactly what deep linking does: it allows an app to open specific content directly through a URL, bypassing the homepage and landing you right where you want to be. So, whether it's sharing a Facebook post, sending a WhatsApp message, or viewing an Instagram story, deep links are everywhere — and they’re crucial for user experience in mobile apps.
For iOS, deep links are managed through the
apple-app-site-association file, and for Android, it's handled by the assetlinks.json file. These files need to be hosted properly in the root of your web server, under a .well-known/ directory, and that’s where AWS Amplify comes into play if you are using Amplify hosting for Angular project.Now that we understand what deep linking is and why it’s important, let’s get into the technical part. In an Angular project, the
apple-app-site-association file should be placed inside the src/assets/.well-known/ directory. This allows Angular to copy the file into the build output, ensuring it gets served correctly when the app is deployed.Here’s the folder structure you need to follow:
1
2
3
4
src/
assets/
.well-known/
apple-app-site-associationAnd the contents of the
apple-app-site-association file should look like this:1
2
3
4
5
6
7
8
9
10
11
{
"applinks": {
"apps": [],
"details": [
{
"appID": "TEAM_ID.BUNDLE_ID",
"paths": ["*"]
}
]
}
}This file essentially tells iOS which app should handle specific deep links and what paths are allowed. For instance,
* means any path within the app can be opened via a deep link.At this point, the file is in the right location, but we need to make sure Angular knows to copy it to the build output when we run the build command. This can be done by modifying the
angular.json file.In the
assets section of your angular.json file, you need to add an entry for the .well-known directory to ensure it’s copied during the build process:1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"architect": {
"build": {
"options": {
"assets": [
"src/favicon.ico",
"src/assets",
{
"glob": "**/*",
"input": "src/assets/.well-known",
"output": "/.well-known/"
}
]
}
}
}
}
This ensures that when you build the app, the
.well-known folder (and everything inside it) is copied into the root of the final build output.Is it done ? No there few more steps are pending.
Here’s where things got a bit tricky for me. AWS Amplify doesn’t automatically serve files like
apple-app-site-association with the correct headers, and it also doesn’t automatically rewrite URLs to .json format when needed.In my initial attempt, I added the rewrite rule for
.well-known/apple-app-site-association to be rewritten to .well-known/apple-app-site-association.json. While this worked fine for that specific URL, the rest of the website went down for about two hours. It took me a while to realize that the order of the rewrite rules was causing the problem.I had added the
.well-known rule first, followed by other rules for the rest of the website. However, this sequence made the Amplify rewrite engine get stuck, causing an issue where the website would not load as expected. Although the .well-known URL was working fine, the other pages were not. It was a frustrating situation, and I realized that the sequence of the rewrite rules was the root cause of the issue.After some troubleshooting and a bit of trial and error, I figured out that the correct order of rewrite rules was essential for everything to work properly. I deleted all the previous rules and started fresh, ensuring the rewrite rules were correctly ordered.
Here’s how I corrected it:
- I placed the
.well-knownrule first in the sequence. - Then, I added the rewrite rules to exclude
.well-knownand include other URLs for the rest of the website.
I added a rewrite rule to ensure that requests to
/apple-app-site-association are correctly rewritten to .apple-app-site-association.json. This step was important because iOS expects the file to be in .json format, but users might request it without the extension.I added the following rewrite rule to handle that:
1
2
3
4
5
{
"source": "/.well-known/apple-app-site-association",
"target": "/.well-known/apple-app-site-association.json",
"status": "200"
}Additionally, I configured a default rewrite rule to handle non-asset URLs and redirect them to the main
index.html for proper routing in the Angular app:1
2
3
4
5
{
"source": "/^(?!\.well-known/)(?!.*\.(css|js|jpg|jpeg|png|gif|svg|woff|ttf|eot|ico|mp4|mp3|json)$).*",
"target": "/index.html",
"status": "200"
}
This ensures that non-asset URLs are routed to the
index.html page, which is typical for single-page applications (SPAs) built with Angular.Once everything was set up, I deployed the application to AWS Amplify. After deployment, I tested the URL where the
apple-app-site-association file should be served, and everything worked as expected:https://your-amplify-app-url/.well-known/apple-app-site-associationI verified that the file was accessible and confirmed that it was being served with the correct content type and caching headers.
To verify that the
apple-app-site-association file is being served correctly, you can use Apple's verification tool:https://app-site-association.cdn-apple.com/a/v1/yourdomain.comThis URL should return the contents of the
apple-app-site-association.json file and show that it's being served with the correct Content-Type (application/json). If it works, your iOS deep linking is correctly configured.While this blog focuses on iOS deep linking with AWS Amplify, it’s worth mentioning that Android also requires a similar configuration. For Android, you’ll need to set up the
assetlinks.json file in the same .well-known/ directory. The process is very similar to what we’ve done for iOS, and once set up, deep linking will work seamlessly across both platforms.Setting up deep linking wasn’t easy, but it was incredibly rewarding. I learned how to handle iOS and Android deep linking in an Angular app, how to host the necessary files on AWS Amplify, and how to configure the right rewrite rules for proper routing. What seemed like a daunting task at first ended up being a great learning experience.
By following these steps, you should be able to set up deep linking for your Angular app hosted on AWS Amplify. I hope my journey helps you navigate this process more smoothly and efficiently!
Happy coding, and may your deep links always work perfectly!
Comments
Log in to comment