Skip to main content

Setting up universal links

If a user that had your application installed clicks on a universal link (e.g. in a Google search's result), instead of opening your web shop the same page gets opened in the application. On Android, these links are called app links. This document refers to Android's app links as universal links.

Universal links work the following way:

  1. When a user opens your application for the first time, it downloads a configuration file from your website. This file authenticates the app with your website and configures the device to redirect links that point to your website to the app.

  2. When next time the user selects a link that points to your website, the app makes a request to the original URL of the link and parses the webpage. It searches for a meta tag that contains the app-specific link for that webpage. If the webpage contains a valid link in a meta tag the app opens the corresponding view.

  3. If the webpage does not contain a meta tag with the app-specific link then a popup will be shown to the user informing them that the content could not be found. The user will then have the option to proceed to the app or continue to the web browser instead.

    Important

    When the app requests the webpage client side JavaScript will not be run. This means that adding the meta tag with client JavaScript will not work. It needs to be added by the server.

In the case of iOS applications, the device may work in a different way than how you configure.

When a user taps a universal link that you handle, iOS also examines the user's recent choices to determine whether to open your app or your website. For example, a user who has tapped a universal link to open your app can later choose to open your website in a browser by tapping a breadcrumb button in the status bar. After the user makes this choice, iOS continues to open your website in the same browser until the user chooses to open your app by tapping OPEN in the Smart App Banner on the webpage. Learn more about this behavior in Apple's developer docs.

Supported browsers​

The following browsers support deep links, and hence universal links to your app:

  • Safari
  • Firefox

To set up universal links, perform the following steps:

  1. Upload and serve the configuration files on your website for both iOS and Android:

    1. To enable universal links for your iOS application:

      1. Upload the Apple App Site Association file provided by NewStore to the .well-known directory on your server.
      2. Serve the file with the content-type application/json.
      3. Serve the file with HTTPS. The file path must follow this format: https://yourdomain/.well-known/apple-app-site-association.

    2. To enable universal links for your Android application:

      1. Upload the Asset Links file provided by NewStore to the .well-known directory on your server.
      2. Serve the file with the content-type application/json.
      3. Serve the file with HTTPS. The file path must follow this format: https://yourdomain/.well-known/assetlinks.json

    3. Test if Google can access the files. To do so, use the following link: https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=https://yourdomain&relation=delegate_permission/common.handle_all_urls (replace yourdomain). As a result, you should see the following text: *********************ERRORS*********************\nNone!\n

  2. Set up meta tags on the pages:

    1. Create deep links for each page that you want to redirect.

      When the user taps on a link, the app uses the information in the deep link to know which view to open.

      1. The app supports deep links to the following screens. The list uses hs as the protocol. Replace it with the protocol for your app.

        • the home screen: hs://home
        • a category product lister: hs://categories/123 (replace 123 with the URL-encoded ID of the category)
        • a product detail screen: hs://products/123 (replace 123 with the URL-encoded ID of the product)
        • the search screen: hs://search/query%20goes%here (the query at the end of the URL should be URL encoded)
        • the favorites screen: hs://favorites
        • the lookbooks overview screen: hs://lookbook
        • the lookbook detail screen: hs://lookbooks/123 (replace 123 with the URL-encoded ID of a lookbook)
        • the cart: hs://cart
        • the order history screen: hs://account/order
        • the loyalty vouchers screen: hs://account/vouchers
        • a content extension: hs://contentextension/?url=aHR0cHM6Ly93d3cubWFybGllc2Rla2tlcnMuY29tL2VuLW5sL2ZpdHRpbmctcm9vbS5odG1s&title=fitting%20room (the value of the URL parameter should be a base64-encoded URL, the value of the title parameter should be URL encoded)

        Note for SFCC customers: if a product is a master product, use a variation ID instead of the master ID.

      2. Use deep links with filters.

        You can create deep links to a category with a filter. The user will be redirected to a new product list with only products that correspond to those filters.

        Use the following parameters in the filters:

        • The title parameter will be the name of the resulting product list, that will be shown in the app. This parameter is optional, if omitted the name of the selected category will be shown.
        • The title of the product list, will need to be URL encoded. As you will see in one of the following examples a name as “Green and Blue” needs to be written as Green%20and%20Blue.
        • The category parameter indicates the category on which the filter will be applied. This parameter is optional, if omitted the root category will be selected.
        • The first parameter filters[$i][attribute] describes the attribute being filtered on.
        • The additional parameters describe the acceptable value or values. At least one acceptable value is required: filters[$i][in][$j]=$value.

        Filters are numbered, starting from 0 ($i). Acceptable values {value} are also numbered, starting from 0 ($j).

      3. Examples

        Deep link with filter:

        hs://productlist?title={name_in_the_app}&category={category_id}&filters[0][attribute]={attribute_id}&filters[0][in][]={attribute_value}

        Deep link with filter, to show a page with Adidas products of size 2:

        hs://productlist?title=Adidas&category=2&filters[0][attribute]=brand&filters[0][in][]=ADIDAS&filters[1][attribute]=size&filters[1][in][]=2

        Deep link with filter, to show green or blue products in category 12:

        hs://productlist?title=Green%20and%20Blue&category=12&filters[0][attribute]=color&filters[0][in][0]=green&filters[0][in][1]=blue

      4. Test the deep links. To do so, open the links in a browser on a device where the application is installed. Tip for iOS: if your Notes on the device syncs with your Mac, copy the deep links into a Notes entry to share them with your device.

    2. Add the following HTML tags to the HEAD of the pages:

      <meta property="al:ios:app_name" content="Store Name">
      <meta property="al:ios:app_store_id" content="{appstore_id*}">
      <meta property="al:ios:url" content="{storename}://categories/432/">

      The al:ios:url meta tag contains the deep link.

      Important

      Adding the meta tag with client JavaScript will not work. Read more about this in the first section of this article.

Emails that are sent from Salesforce Marketing Cloud (SFMC) contain links to your website such as a Product detail page, Product lister page etc. Even if you have universal links enabled, these links in the email do not open the app because the domain is an SFMC domain and not the domain of the website. This domain usually starts with click.

For the device to know that it can open the app from these links, the following conditions need to be met: