• Home
  • Pugpig Bolt
  • URLs, Domains and Linking

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 October 27th, 2023

  • Pugpig Bolt
    Bolt apps Content and Workflows Bolt CMS Pugpig Distribution Service URLs, Domains and Linking Bolt Search Authentication and Subscriptions Bolt Analytics Push notifications Bolt Release Notes Debugging Advertising App stores Consent management
  • Pugpig Site
    Site Search URLs, Domains and Linking Content Management System Analytics SEO Advertising Consent Management Platform Site Release Notes Debugging Authentication and Subscriptions
  • Pugpig Archive
  • Working with Pugpig
    Pugpig Support Releasing new versions Pugpig Packs & Agreements Pugpig Policies
  • Pugpig Consulting
+ More

Development needed

Your development team will need to implement a redirect service and change some files on your server to allow this to work.

The need for canonical URLs only applies if you have a separate website and/or CMS. If you only have Pugpig app and site and only use our CMS, then this will all be handled for you.

 

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/

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! It probably isn't a good idea anyway.

 

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

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.

redirect canonicalize

Was this article helpful?

Yes
No
Give feedback about this article

Related Articles

  • Data Consent & App Tracking Transparency
  • Returning to the app
  • Article cache times in your app
pugpig logo white
Navigation
  • Products
  • Customers
  • News
  • Podcast
Contact
  • Contact us
  • LinkedIn
  • Twitter
Technical Support
  • Status Page
  • Documentation
  • Customer Support
Corporate
  • Company
  • Jobs
  • Privacy Policy

© Kaldor Ltd. 2022

Powered by Pugpig

Expand