Configure and link your App Clips

Hello and welcome to WWDC.

Hi, everyone. I'm Ada, an engineer on App Clips. I'll be joined by my colleague Luming today to show you all you need to know about linking to your app clips.

App Clips provides an entry point for your users to experience your app with minimum friction.

When your users need your app's functionality to perform a task, your app clip is presented to the user seamlessly with a deep-link navigation.

This session covers what you have to do to handle linking into your app clip and configure the linking experience. First, let's take a look at an example of how one can perform a task with an app clip.

Imagine you come across a smoothie stand. You really want a nice, cold smoothie.

You find an NFC tag with a sign that says, "Tap here to order." You tap the tag and a card pops up at the bottom of the screen which has a brief description of the smoothie-ordering app clip.

When you tap on the "Open" button, the app clip is launched on your device, taking you directly to the smoothie-ordering page.

You complete the purchase with Apple Pay, and now you have a smoothie in your hand.

The linking magic happens in these steps. The NFC tag actually encodes a URL that's registered with an app clip experience, which I'll explain later in this session.

Once you tap "Open," the app clip gets launched with a URL that is passed via an NSUserActivity, and the app clip takes you directly to the ordering page.

Besides NFC, app clip links can also appear in other places.

These are URLs that could be encoded in physical tags or visual codes, or associated with a physical location on the map. Let's go through each of these linking methods.

As I mentioned in my example earlier, an NFC tag can encode an app clip URL that users can tap their phones on to open an app clip.

An app clip URL can also be encoded in a QR code, which people can scan to open an app clip.

App clip links can show up on the Maps place card for registered businesses, and also in the Siri nearby suggestions.

You can also open an app clip from Safari. If your web page is configured with a Smart App Banner for app clip, people can tap the "Open" button in that banner to open the app clip.

And when they send an iMessage with that web page's URL, it's presented as a special app clip link bubble, which gives the user a choice to open the link in the app clip, or in Safari.

And to give you an even better experience, later this year, Apple will be releasing the new app clip codes, which is the best way for your users to discover your app clip.

It's visually beautiful and distinct, so when they see one, they know there's an app clip waiting for them.

Each app clip code encodes a URL. Apple will be releasing tools later this year that can create these beautiful visual codes.

Now that we've looked at the different ways people can follow links into your app clip, let's go through the steps an app clip developer needs to do to set up this linking experience.

First, you have to make changes to your web server and your app clip project so these links can be handled by the app clip.

Next, you have to configure the app clip card, which is the card that introduces the user to the app clip and is part of the app clip experience.

You can set up the default and advanced app clip experiences on App Store Connect.

Lastly, let's configure the Smart App Banner to show your app clip on your web page. If the contents of your web page can be delivered as a better and more streamlined app clip experience, consider adding this banner to provide a way for your users to get to the app clip from that web page.

First, let's start with configuring your web server and your app clip for link handling.

The association between your website and your app clip must be validated for the app clip to be able to present contents in place of the website's URL.

To securely associate your app clip with the server, you will need the apple-app-site-association file on your web server, along with the appropriate associated domains entitlement on your app clip.

Then you have to update the code in your app clip to handle links from incoming NSUserActivities.

First, let's update the apple-app-site-association file on the web server.

This file is located in a .well-known subdirectory in your server's root folder.

If you have set up universal links for your app before, you probably have this file already set up on your server, and the root dictionary has other entries already, such as web credentials and app links.

To declare the new app clips association in this file, add another entry in the root dictionary with the key "appclips" and the value containing a dictionary containing a single "apps" key that is set to an array containing your app clips app identifier.

Next, let's update the app clip project to add the associated domains entitlement.

In Xcode, navigate to your project settings and add the associated domains capability.

Under domains, add a new string "appclips:your-website-domain." Now that both your website and your app clip have been set up with associated domains, let's add code to handle NSUserActivity, which contains the URL passed into your app clip.

If your app clip has adopted the new SwiftUI app life cycle, this is how you would add a handler for the web-browsing userActivity. In that method, you can get the web page URL property from the NSUserActivity.

Then you can parse that URL and direct the user to the linked content.

Keep in mind that once the user upgrades from the app clip to the app, navigating to that app clip link will actually open your app, rather than the app clip.

So make sure your app also has similar code for handling the URLs for universal links as well.

If your app clip uses the UIKit's SceneDelegate life cycle, here's some similar code for handling incoming user activities in the UISceneDelegate.

To learn about how to set up associated domains, and handling NSUserActivities, please refer to the "What's New in Universal Links" sessions.

To test the URL handling code in your app clip in Xcode, you can specify a test URL to be passed to your app clip. Open up the scheme editor in Xcode. Select the "arguments" tab.

Under "environment variables," specify the _XCAppClipURL variable.

Now when you run your app clip from Xcode, it'll be launched with this URL.

Now that we're done configuring the web server and the app clip, let's configure the app clip experiences.

Each app clip experience starts with the app clip card that the user sees when they tap on an app clip link.

It shows the information about the app clip, and asks for the user's consent to open it.

When coming up with the metadata to use to configure the app clip card, please follow these requirements on the length of the title and subtitle for the optimal layout of the card.

There are also requirements for the image's size, aspect ratio and format for the best user experience across all devices.

The image you choose should match the experience this app clip action delivers.

Now let's set up the app clip card on App Store Connect.

After you've delivered a build containing both your app and your app clip to App Store Connect, the app clip should be visible on App Store Connect with a new app clip configuration section.

This is where you can start setting up the default and advanced app clip experiences.

The metadata for the default app clip experience includes the app clip card's image, subtitle and the verb for the action. There's a list of predefined actions you can choose from. This metadata will be used in a Smart App Banner in Safari, and in the app clip link bubble in Messages. And also in the app clip card when it's presented.

If you want your app clip to be accessible from more than just Safari and Messages, you must set up an advanced app clip experience by clicking the "Get Started" link here.

Each advanced app clip experience is tied to a URL which can be encoded in a physical tag, such as the NFC tag, or a QR code, so your app clip can be launched from these physical invocation methods.

After clicking through some introduction screens, you will arrive on this page