Article

Defining Relevant Shortcuts for Your App

Provide Siri relevant shortcuts to display on the Siri watch face.

Overview

The Siri watch face can suggest shortcuts to the user based on a situation, time of day, or location. You determine which actions in your app are pertinent to the user and may be something they’d like to do in the future, such as starting a workout when arriving at a gym. Your app tells Siri about these actions by specifying them as relevant shortcuts.

Create a Relevant Shortcut

To let Siri know about relevant shortcuts for your app, start by creating an INIntent with a system-provided or custom intent, or an NSUserActivity object for each action. Next, create an INShortcut object for each intent and user activity. Use the shortcut to create an INRelevantShortcutRole object, and set the shortcutRole to provide a hint to Siri as to the purpose of the shortcut: to perform an action or display information.

Listing 1

Create a relevant shortcut for starting a workout

// Add an intent to the list of suggestions. To create
// a shortcut from an intent, the intent must be valid.
if let shortcut = INShortcut(intent: startWorkoutIntent) {

    let relevantShortcut = INRelevantShortcut(shortcut: shortcut)
    relevantShortcut.shortcutRole = INRelevantShortcutRole.action

}

Add Relevance Providers

To give Siri a hint about when to suggest the shortcut to the user, add one or more providers to the relevanceProviders property on the relevant shortcut. Relevance providers let you specify parameters such as a particular situation, date, time, and location that indicate the shortcut may be relevant to the user. For example, you can instruct Siri to suggest starting a workout when the user arrives at the gym.

Listing 2

Add a location provider to the relevant shortcut

// Add an intent to the list of suggestions. To create
// a shortcut from an intent, the intent must be valid.
if let shortcut = INShortcut(intent: startWorkoutIntent) {

    let relevantShortcut = INRelevantShortcut(shortcut: shortcut)
    relevantShortcut.shortcutRole = INRelevantShortcutRole.action

    // Create a location provider for Apple Park Fitness Center.
    let location = CLLocationCoordinate2D(latitude: 37.336_971, longitude: -122.013_050)
    let region = CLCircularRegion(center: location, radius: 0.1, identifier: "Apple Park Fitness Center")
    let locationProvider = INLocationRelevanceProvider(region: region)
    relevantShortcut.relevanceProviders = [locationProvider]

}

Don't combine an INDailyRoutineRelevanceProvider for a time-based situation with an INDateRelevanceProvider, like INDailyRoutineRelevanceProvider.Situation.evening and 8 p.m.; the outcome can be unpredictable. Instead, provide multiple relevant shortcuts for each scenario, that is, provide a relevant shortcut for INDailyRoutineRelevanceProvider.Situation.evening and a second one for 8 p.m.

Applying multiple locations relevance providers to a relevant shortcut creates similar problems. Instead, provide a relevant shortcut for each location.

Set Relevant Shortcuts

Continue creating the relevant shortcuts for your app, storing each one in an array. After you've created and stored the shortcuts, inform Siri of the relevant shortcuts by using the default relevant shortcut store to call setRelevantShortcuts(_:completionHandler:), passing in the array of relevant shortcuts.

Listing 3

Add a relevant shortcut to start a workout when arriving at the gym

var relevantShortcuts:[INRelevantShortcut] = []

// Add an intent to the list of suggestions. To create
// a shortcut from an intent, the intent must be valid.
if let shortcut = INShortcut(intent: startWorkoutIntent) {

    let relevantShortcut = INRelevantShortcut(shortcut: shortcut)
    relevantShortcut.shortcutRole = INRelevantShortcutRole.action

    // Create a location provider for Apple Park Fitness Center.
    let location = CLLocationCoordinate2D(latitude: 37.336_971, longitude: -122.013_050)
    let region = CLCircularRegion(center: location, radius: 0.1, identifier: "Apple Park Fitness Center")
    let locationProvider = INLocationRelevanceProvider(region: region)
    relevantShortcut.relevanceProviders = [locationProvider]

    relevantShortcuts.append(relevantShortcut)
}

INRelevantShortcutStore.default.setRelevantShortcuts(relevantShortcuts) { (error) in
    if let error = error {
        print("Failed to set relevant shortcuts. \(error))")
    } else {
        print("Relevant shortcuts set.")
    }
}

Replace Relevant Shortcuts

There isn't a way to add relevant shortcuts to the list already set by your app. Instead, you must replace the list by following the same steps previously mentioned:

When you've completed these steps, the new set of relevant shortcuts takes the place of the previous one. If you want to delete all relevant shortcuts defined by your app, call setRelevantShortcuts(_:completionHandler:), passing in an empty array.

Replace the list when your app needs to add or remove a relevant shortcut. It isn't necessary to replace the list more than once a day, and resubmitting the same set of relevant shortcuts more often provides no benefits.

See Also

First Steps

class INRelevantShortcut

An object that defines a shortcut and its relevance to the user.

class INRelevantShortcutStore

An object that saves relevant shortcuts.