A client recently asked me to help them implement a custom smart banner solution, inspired by what some other major companies in their industry were doing. I’m going to cover some of the related techniques and features first, before going over the implementation. If you’d like to jump directly to the step-by-step, click here.

Smart Banners

Smart Banners are an iOS native method of promoting App Store apps by displaying a banner on a website simply by adding a meta tag.

A screenshot of an example smart banner

Using this method has quite a few distinct advantages over implementing your own solution:

  1. Simple implementation: A single meta tag is all you need
  2. Consistent look: You can expect the banner to look the same on all devices
  3. No JS/CSS/HTML injection: The banner isn’t actually injected into the website, but instead displayed as an overlay by Safari. This avoids potentially messy interactions with the website
  4. Knows if the app is already installed: Since Safari is part of iOS, it can display either a “View” or “Open” link depending on whether you have the app installed
  5. Affiliate program built-in: Promote your app by incentivizing publishers to show your smart banner on their websites (more info at https://www.apple.com/itunes/affiliates/)
  6. Deep link support: You can have the banner’s “Open” button deep link into a particular part of the app

All in all, a very powerful tool compared the small amount of implementation work. A full implementation guide can be found here.

Customizing

For brand-conscious folks, advantage number 2) can actually be a downside. You can’t customize the look of the smart banner at all. Your only alternative is to style your own banner and conditionally display with with some javascript and cookies. I’m not going to cover that here since it’s not my lane. Rather, I’d like to talk about how build a link for your custom smart banner that will open the app if it is installed (with optional deep linking) or the app store if it isn’t, using a feature called Universal Links.

If you’re already familar with Universal Links, feel free to skip to the next section. Otherwise, here’s a little bit of background and history.

Apple has supported Inter-App Communication using custom URL schemes for a long time. You can use them to deep link into your app from push notifications or other apps. Originally, you could even figure what apps were installed on a user’s device by querying if a particular scheme could be opened. Apple eventually had to bring the boom down after some developers started exploiting this feature, and custom schemes are more limited now. Another downside of schemes is that, unlike with App IDs for example, there’s no infrastructure in place to make sure only you are using your custom scheme. And there’s no procedure in place for what happens if two apps register the same scheme. And finally, if no app is registered to handle a particular scheme, iOS just shows you an ugly error message.

To work around all this and more, Apple introduced Universal Links in iOS 9. Rather than using custom schemes now, you can use regular https links that are backed by a real website. Universal Links improve upon schemes in a few ways:

  1. Security: Association between an app and a web site has to be established bi-directionally, from app to site and vice-versa
  2. User Experience: If the app is not installed, the user will be able to interact with the website instead
  3. Customizability: The app can be associated with just a subset of pages on a domain, and more than just one domain

There are plenty of guides on how to get started with Universal Links, for example at Apple, or here. Branch.io even has a validator for the Apple App Site Association file you have to create. I’d recommend checking these out if you’re unfamiliar with Universal Links.

There are four steps to creating the link for your custom smart banner. I’ll cover each in turn and explain the how and why.

Step 1: Create a separate (sub)domain

Let’s say your website is at https://www.example.com. If you want to send the user to your app, redirecting to a URL on the same domain is not enough. For usability reasons, the user is required to initiate the interaction (e.g. tap a link), and the target URL must be in a different context (i.e. a different domain or subdomain). We will use app.example.com.

Step 2: Create a page that redirects the user to the app store

We need a page that will guide the user to the app store if the they don’t have your app installed. Ideally, this page should have some relevant content and a link to the app store (like a marketing page for your app) in case the user declines to be sent to the App Store, but it can also just serve the redirect via HTTP header. In my testing, the latter method caused the browser to stay on the page with the smart banner, but your mileage may vary.

As the URL for this page, we will use https://app.example.com/app-store. Important: This page must be served via HTTPS. Thanks to https://letsencrypt.org/, that can be done for free now.

Step 3: Create Apple App Site Association file

This is a special JSON file that allows a web site to declare which URLs can be opened in an associated app (and a few other things). This file must be uploaded to https://app.example.com/.well-known/apple-app-site-association. Just like the page in step 2, HTTPS is required.

Here’s how the file would look in our case. The appID is your team ID (also know as prefix) followed by a dot and the bundle ID. Check Apple’s Universal Links Guide for more information. You can validate the resulting file here.

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "ABCD1234.appBundleId",
                "paths": ["/app-store"]
            }
        ]
    }
}

Step 4: Update App capabilities

Finally, the app needs to declare association with the domain from step 1. To do this:

  1. Open the project in Xcode
  2. Go to “Capabilities”
  3. Enable “Associated Domains”
  4. Add the following entry based on the domain from step 1: applinks:app.example.com

That’s it.

You can now test your custom smart banner by deploying the app to a device and visiting a page with the custom banner code in Safari.