Canonical URLs
Learn how to link your website and app URLs to make links on your domain open in the app
Written by Benji Weiser
Updated at January 10th, 2025
Table of Contents
Important Redirect Service Notice
Important. This document refers to the implementation of a redirect service which many of our customers have in place. However, we realise that this can be difficult for some customers to implement, depending on their internal setup and choice of hosting/CDN partner.
We have since made some improvements to implement this service on behalf of our clients. So we now recommend anyone considering implementing canonical URLs to submit on 3.23+ now that we host the redirect service.
Note: This feature is available as of Bolt 3.23+. Users who have not updated to 3.23+ will see the web site page in an in app webview. If your app already has redirects enabled, and is already on v3.23+, this can all be handled with server side config i.e no app update required. If you are configuring the redirects and the alias domain for the first time OR changing the alias domain itself, an app update is required.
If existing customers would like to migrate from their own redirect service, please get in touch with your customer success manager as there are a few considerations to take into account
Switching to Pugpig Redirect Service from your own hosted redirection service
If you have users on < Bolt v3.23+, you'll need to continue running your redirection service in parallel with the Pugpig Redirect Service.
This is because only users on Bolt v3.23+ will benefit from the Pugpig hosted service, so you'll need to rely on your own redirect service to redirect users on < Bolt v3.23+ to app URLs from the website/canonical URLs.
Once enough users have moved onto v3.23+, you can sunset your hosted redirection service and fully rely on the Pugpig one.
What are canonical URLs?
With the implementation of canonical URLs you can share your website link everywhere, and so can your users, without worrying where people will end up. Existing app users will end up opening the app in the correct place, while anyone without the app installed, or anyone who opens the link on a laptop or desktop, will go to the website as intended.
Universal Links/App Links
On iOS these links are known as Universal Links and on Android they are known as App Links.
For our clients that do not have canonical URLS, they will share deep links to the apps using the app domain, rather than the web one. However, with canonical URLs in place you won't have to worry about switching between the two. You should always use the canonical URL. The main advantages of using your canonical website URLs include:
- A user will end up in the right place, regardless of how they followed the link. This could include email newsletters, social networks, messaging apps and push notifications
- You can send the same URL for app push notifications and web notifications
- Users that do not have the app will end up on your website. If you use app URLs, they'll end up on a standalone web holding page.
- You don't need to think about or worry about different URL structures for the app
- You never need to share the app domain with anyone
- Sometimes you may want to send a push very quickly - even if the article is not yet in your feeds or on your website section pages. As long as the individual article is live on your website, the user will see the correct content
If you want to share https://www.yourdomain.com/mystory and you want this to open in the app in the correct place, there is some work to be done. The most important prerequisite is that you know the app URL to the page on your web site in advance (see step 3 below).
Having this information means you should also consider implementing native smart banners on your website so that users that are browsing your site will be told about your app. But that's a separate topic.
How it works
This works in the following way:
- User receives a link to www.yourdomain.com/story/12345
- If the user has the app installed, the URL is configured to open in the app, and the article exists in the app, the app will open
- The app will make a request to your server for the URL with a header so your server knows it is from the app
- The redirect service will send a redirect back telling us which URL on our server matches the story, for example https://app.yourdomain.com/story/12345/content.html
- The app will open this story in the relevant place. If the target of the redirect does not exist in the app, we will open the original URL to your web site in an embedded browser.
You may notice different behaviour in terms of how links to your app content (or website URLs that are set up to deep link into your app via a redirect service, whether that is the Pugpig Redirect Service or your own) behave when opened from other apps, such as social media, email and messaging apps.
If an app uses an in-app browser on iOS, the in-app browser will intercept the deep link and prevent the user from being immediately linked out to the publisher's app. So, for instance, this is the behaviour you'll see in X (formerly Twitter) on iOS - the article will load in Safari within the X app. You'll observe the same thing happens whether the content being linked to belongs to a Pugpig app, or others.
It is the choice of app developers whether they use in-app browsers or take users directly to the standalone browser. Some apps, such as Gmail, allow the end user to select whether an internal browser is used or not, but most don't. On Android, it is almost always an external browser so you should see more consistent deep linking behaviour from social media apps.
Essentially the behaviour is determined by the respective apps but, as Android apps almost always open an external browser, we would expect the much more consistent deep linking behaviour than on iOS.
Step 1: Plan which domains and URLs you want to open in the app
Before diving in, you need to decide which URLs should open in the app. Often it will just be article pages. Any pages that are not mapping to a URL in the app will open in the app in an embedded web view. Ideally your URL structure will make this easy to determine, for example, if all articles start with /story/
Beware! Many customers choose to simply open all URLs in the app. However, if you have a hard paywall then this is not a good idea as anonymous users won't be able to access many pages of your site!
For the article URLs, you need to ensure there is a mapping between the URLs on your site and the URLs in the app. The Pugpig team can help change the Pugpig URLs if the format does not include your unique article ID.
Step 2: Associate relevant URLs on your domain with the app
You’ll need an app association file on your server that tells the operating system which URLs on your domain to open in the app (for example, if all the stories are under /story/ you can target that). You may also want to include the home page or section pages if you'd prefer these to open in the app. This involved creating files on your server from both iOS and Android:
- iOS Documentation: (apple-app-site-association) - https://developer.apple.com/documentation/xcode/supporting-associated-domains - we will give you the App ID if you do not know it. You can use the example below to configure the file on your end. Make sure you include the path such as '/story/'.
Example of apple-app-site-association (which allows all paths){ "applinks": { "apps": [], "details": [ { "appID": "XXXXXXXX.com.company.app", "paths": [ "*" ] } ] } } - Android Documentation (assetlinks.json): https://developer.android.com/training/app-links/verify-android-applinks#web-assoc - we will give you the fingerprint of the app if you do not know it
Android also has manifest.json which you should create, although it is not strictly needed for the deep linking.
Example of assetlinks.json[ { "relation":[ "delegate_permission/common.handle_all_urls" ], "target":{ "namespace":"android_app", "package_name":"com.packageid.app", "sha256_cert_fingerprints":[ ] } } ]
Note: On both Android and iOS, the list of domains needs to be included in the app bundle at submission time. On Android, the URL paths and patterns are also embedded in the app, so any change to this will require a new app update. On iOS, the server-side site association file configures the URL paths and patterns, so app releases aren't needed to reconfigure these.
You can get links to these files under More Information on the content endpoint in the Pugpig Distribution Service.
At the same time we'll handle the association from the app.
Step 3: Agree URL format
Note: this will not affect canonical URL setup - nonetheless we'll need to make sure your app URLs have a suitable format - the default app article URL path from Express follows this format /date/article-headline-xxx-yyy-zzz
If the article headline is ever edited after publish, this can cause duplicates in Search results, analytics tracking etc. We'd always recommend to use this URL format instead as the article GUID should never change - /story/guid
The support team can easily update all app URLs for you to follow our preferred structure, as long as the GUID is sent to us in your feeds.
See here for more information on how to choose the URL structure for your content
Step 4: Provide the redirection service
Pugpig will provide the redirection service. In order to do this, we need to ensure your content feed provides us with your website/canonical URL.
Query Strings on the Location Header
At the moment, we advise against using query strings in the responses from your redirect server. For example, ideally do not include ?utm=12345 on the Location URL. These will be ignored by the app and have a small performance implication.
Step 5: Test the redirection service
Test this end to end by clicking on many different deep links! Also ensure that when you click around on your website, the redirect does NOT happen.
Additional considerations
On iOS, the App Smart Banner, which usually directs users to the store to install your app, will behave differently if the app is installed and the web page the users is on has a valid deep link into the app.
In this case the smart banner will display an “Open” CTA, where tapping will deep link you directly into the page.