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.

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.

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/

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. 

We will provide a redirection service that will redirect from your domain to the Pugpig domain and URL. In order to ensure this only happens when the request comes from the app, you need to check for the header x-pugpig-bolt-reader. This will be a server side redirect (30x). For example:
https://www.vanity.com/mystory -> https://app.vanity.com/mystory/content.html

When this is in place, the app will open when a user hits https://www.vanity.com/mystory and then follow the redirect that makes sure the user ends up in the right place.

Example call:

>>> curl -I -H https://www.yourdomain.com/story/123456/

HTTP/2 302
Location: https://app.yourdomain.com/story/123456/content.html

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.