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 the majority of our clients, if they want to share deep links to the apps they’ll use the app domain, rather than the web one, but with canonical URLs in place you won't have to worry about switching between the two.

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, and the URL is configured to open 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
• Your redirect services 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

How to set it up

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
  

  {
     "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

We'll need to make sure your URLs have a suitable format and we have the right information to be able to link app and web. This is usually all provided in your content import method, but best to confirm.

See here for more information on how to choose the URL structure for your content

Step 4: Provide the redirection service

You will need to 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 need to be a server side redirect (301 or 302). For example:
https://www.vanity.com/mystory -> https://app.vanity.com/mystory/content.html

You could also include redirects for the home page or section pages, for example:
https://www.vanity.com/ -> https://app.vanity.com/
https://www.vanity.com/news/ -> https://app.vanity.com/t/news/

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 'x-pugpig-bolt-reader: true' 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.