45. An Overview of Siri Shortcut App Integration

When SiriKit was first introduced with iOS 10, an app had to fit neatly into one of the SiriKit domains covered in the chapter entitled “An Introduction to SiriKit” in order to integrate with Siri. In iOS 12, however, SiriKit was extended to allow an app of any type to make key features available for access via Siri voice commands, otherwise known as Siri Shortcuts. This chapter will provide a high level overview of Siri Shortcuts and the steps involved in turning app features into Siri Shortcuts.

45.1 An Overview of Siri Shortcuts

A Siri shortcut is essentially a commonly used feature of an app that can be invoked by the user via a chosen phrase. The app for a fast-food restaurant might, for example, allow the user to order a favorite lunch item by simply using the phrase “Order Lunch” from within Siri. Once a shortcut has been configured, iOS learns the usage patterns of the shortcut and will begin to place that shortcut in the Siri Suggestions area on the device at appropriate times of the day. If the user uses the lunch ordering shortcut at lunch times on weekdays, the system will suggest the shortcut at that time of day.

A shortcut can be configured within an app by providing the user with an Add to Siri button at appropriate places in the app. Our hypothetical restaurant app might, for example, include an Add to Siri button on the order confirmation page which, when selected, will allow the user to add that order as a shortcut and provide a phrase to Siri...

45.2 An Introduction to the Intent Definition File

When a SiriKit extension such as a Messaging Extension is added to an iOS project, it makes use of a pre-defined system intent provided by SiriKit (in the case of a Messaging extension, for example, this might involve the INSendMessageIntent). In the case of Siri shortcuts, however, a custom intent is created and configured to fit with the requirements of the app. The key to creating a custom intent lies within the Intent Definition file.

An Intent Definition file can be added to an Xcode project by selecting the Xcode File -> New -> File… menu option and choosing the SiriKit Intent Definition File option from the Resource section of the template selection dialog.

Once created, Xcode provides an editor specifically for adding and configuring custom intents (in fact the editor may also be used to create customized variations of the system intents such as the Messaging, Workout and Payment intents). New intents are...

45.3 Automatically Generated Classes

The purpose of the Intent Definition file is to allow Xcode to generate a set of classes that will be used when implementing the shortcut extension. Assuming that a custom intent named OrderFood was added to the definition file, the following classes would be automatically generated by Xcode:

•OrderFoodIntent – The intent object that encapsulates all of the parameters declared in the definition file. An instance of this class will be passed by Siri to the handler(), handle() and confirm() methods of the extension intent handler configured with the appropriate parameter values for the current shortcut.

•OrderIntentHandling – Defines the protocol to which the intent handler must conform in order to be able to fully handle food ordering intents.

•OrderIntentResponse – A class encapsulating the response codes, templates and parameters declared for the intent in the Intent Definition file. The intent...

45.4 Donating Shortcuts

An app typically donates a shortcut when a common action is performed by the user. This donation does not automatically turn the activity into a shortcut, but includes it as a suggested shortcut within the iOS Shortcuts app. A donation is made by calling the donate() method of an INInteraction instance which has been initialized with a shortcut intent object. For example:

let intent = OrderFoodIntent()

 

intent.menuItem = "Cheeseburger"

intent.quantity = 1

intent.suggestedInvocationPhrase = "Order Lunch"

 

let interaction = INInteraction(intent: intent, response: nil)

 

interaction.donate { (error) in

    if error != nil {

        // Handle donation failure

    }

}

45.5 The Add to Siri Button

The Add to Siri button allows a shortcut to be added to Siri directly from within an app. This involves writing code to create an INUIAddVoiceShortcutButton instance, initializing it with a shortcut intent object with shortcut parameters configured and then adding it to a user interface view. A target method is then added to the button to be called when the button is clicked.

As of iOS 14, the Add to Siri button has not been integrated directly into SwiftUI, requiring the integration of UIKit into the SwiftUI project.

45.6 Summary

Siri shortcuts allow commonly performed tasks within apps to be invoked using Siri via a user provided phrase. When added, a shortcut contains all of the parameter values needed to complete the task within the app together with templates defining how Siri should respond based on the status reported by the intent handler. A shortcut is implemented by creating a custom intent extension and configuring an Intent Definition file containing all of the information regarding the intent, parameters and responses. From this information, Xcode generates all of the class files necessary to implement the shortcut. Shortcuts can be added to Siri either via an Add to Siri button within the host app, or by the app donating suggested shortcuts. A list of donated shortcuts can be found in the iOS Shortcuts app.