Guides and Sample Code

Developer

SiriKit Programming Guide

On This Page

Creating an Intents Extension

Interactions with SiriKit occur through your Intents extension, which is an app extension that you deliver inside your iOS or watchOS app bundle. You must already have an iOS or watchOS app before you can create an Intents extension. The Intents extension handles most interactions with SiriKit, but your app needs to be aware of those interactions and in some cases may have an active role in making them happen.

When adding an Intents extension to your app, you must do the following:

For general information on how to create app extensions, see App Extension Programming Guide.

Configuring Your Xcode Project

Configuring your Xcode project requires several steps. In addition to adding an Intents extension target to your project, you must make some minor changes to your app as well.

To use SiriKit, you must enable the Siri capability in your app. You enable this capability in the same way that you enable other capabilities such as iCloud, push notifications, and in-app purchase. Enabling it adds entitlements to your app that let the App Store know that your app supports Siri.

To enable the Siri capability in your app
  1. Open your app project in Xcode.

  2. In the project settings, select your app target (in iOS) or your WatchKit extension target (in watchOS).

  3. Select the Capabilities tab.

  4. Enable the Siri capability.

    Xcode adds the Siri entitlement to your app. The App Store requires the presence of this entitlement for any iOS or watchOS app containing an Intents extension.

After enabling Siri support, add a new Intents extension target to your project. Adding this target provides the initial files you need to build your Intents extension and configures your Xcode project to build that extension and include it in your app’s bundle.

To add an Intents extension to your app
  1. Open your existing app project in Xcode.

  2. Select File > New > Target.

  3. Select Intents extension from the Application Extension group for the appropriate platform.

  4. Click Next.

  5. Specify the name of your extension and configure the language and other options.

    For an iOS app, enable the Include UI Extension option if you plan to customize portions of the Siri interface.

  6. Click Finish.

After adding your Intents extension target to your project, configure the default Info.plist file provided by Xcode to specify which intents you support. SiriKit uses the information in your extension’s Info.plist file to determine which intents to route to your extension.

To specify the intents that your extension supports
  1. In Xcode, select the Info.plist file of your Intents extension.

  2. Expand the NSExtension and NSExtensionAttributes keys to reveal the IntentsSupported key (iOS and watchOS) and the IntentsRestrictedWhileLocked key (iOS only).

  3. In the IntentsSupported key, add a String item for each intent that the extension handles. Set the value of each item to the class name of the intent.

    This key is required. You can support all of the intents in a given domain or only some of them, and a single extension can support multiple domains.

  4. In the IntentsRestrictedWhileLocked key (iOS only), add a String item for each intent for which you require the device to be unlocked. Set the value of each item to the class name of the intent.

    This key is optional. Some intents, such as those involving financial transactions, always require the user’s device to be unlocked. You can use this key to augment the default list with intents that do not require an unlocked device by default.

    In watchOS, all intents require the device to be unlocked; however, after the watch is unlocked, it stays unlocked as long as the watch remains on the user’s wrist.

When a user utterance is ambiguous enough that it resolves to multiple intents, SiriKit uses the order of the intents in the IntentsSupported key to determine which intent to send to your app. Organize your list of intents by putting the most relevant ones first in the array. Prioritizing your intents is especially important when your Intents extension supports multiple domains with similar semantics. For example, an app that supports both calling and messaging intents might choose to prioritize sending a message over initiating a call.

Some intents may require additional configuration steps for your Xcode project or your app. For example, when implementing a ride booking app, Maps expects you to provide a GeoJSON file that describes the coverage area for your service. For information about any additional configuration steps for specific intents, see the description of those intents in Intents Domains.

Requesting Siri Authorization in Your App

Users must grant permission for your app to use SiriKit. You ask for permission only from your iOS app, but the permissions you receive are granted to both your watchOS app and iOS app. To request permission to use SiriKit, do the following:

  • Include the NSSiriUsageDescription key in your iOS app’s Info.plist file. The value for this key is a string that describes what information your app shares with SiriKit. For example, a workout app might set the value to the string “Workout information will be sent to Siri.” Inclusion of this key in your Info.plist is required.

  • Call the requestSiriAuthorization: class method of INPreferences at some point during your iOS app’s execution.

The first time that your iOS app calls the requestSiriAuthorization: method, the system displays an alert that prompts the user to authorize your app. The alert includes the usage description string you provided in the NSSiriUsageDescription key of your app’s Info.plist file. The user can approve or deny your app’s request for authorization and can change your app’s authorization status later in the Settings app. The system remembers your app’s authorization status so that subsequent calls to the requestSiriAuthorization: method do not prompt the user again.

Apps must have the Siri capability enabled for authorization to succeed. For information about how to enable the Siri capability, see Configuring Your Xcode Project.

Creating Intents for watchOS Apps

Intents in watchOS are almost identical to intents in iOS. In many cases, you can even use the same code on both devices. There are, however, some differences worth noting:

  • The Intents UI framework is not available in watchOS.

  • Not all intents are available in watchOS. For example, the CarPlay domain is not available in watchOS. The INStartVideoCallIntent and INSetMessageAttributeIntent intents are also not available, even though the rest of the VoIP Calling and Messaging domains are.

  • Some intents behave differently on Apple Watch. For example:

    • Siri does not speak on Apple Watch. Instead, all of Siri’s responses are shown as text.

    • When searching for messages, Siri launches your watchOS app to handle the results. Your app must then display these messages to the user.

    • The INRequestRideIntent and INSendMessageIntent intents use an auto-send behavior. Here, the intent is handled automatically without further confirmation from the user, providing a hands-free workflow. This is similar to the way the Messages app works on the watch. Siri does not ask the user to confirm the message. Instead, when the user’s wrist drops, Siri automatically sends the message.

    • For auto-send intents, after the app has been dismissed, any errors passed to the handle method’s completion block are displayed using notifications.

Given these differences, be sure to test the behavior of your intents on both iOS and watchOS.

Additionally, there are a few changes to the way you set up and handle your Intents extensions in watchOS:

  • Your SiriKit extension on Apple Watch needs to support a subset of the intents supported on iOS. You can support fewer intents, but you cannot support more.

  • You set only the IntentsSupported key in your WatchKit extension’s Info.plist file. In watchOS, all intents are restricted when the watch is locked; however, after it is unlocked, it stays unlocked as long as the watch remains on the user’s wrist.

  • The SiriKit extension on Apple Watch shares the custom and global vocabulary from the iOS app. You cannot configure the vocabulary on the watch. It automatically receives all the vocabulary from the iPhone app.

  • The SiriKit extension on Apple Watch shares permissions with the iOS app. If the user attempts to use Siri with the watch before permission is set, Siri prompts the user to continue on iPhone.

  • Donating interactions is not supported on watchOS.

  • When Siri launches your watchOS app, it calls the app’s handleActivity: method, and passes the user activity for the intent.

You can—and in many cases, should—craft a different experience for watchOS and iOS. When building your SiriKit extension on Apple Watch, take the opportunity to rethink the way users interact with your intents. In particular, the watch extension should minimize the number of questions or prompts to the user. For example, when starting a workout session, don’t ask the user for the type of workout. Instead, just select a reasonable default for the user (perhaps based on the user’s most common workout). Streamline and simplify the interaction wherever possible.

For more information on creating Intents for watchOS apps, see watchOS Human Interface Guidelines.

Structuring Your App’s Services

Your Intents extension is an agent that acts on behalf of your app, so it must be able to perform the same services that your app does. Because your app and Intents extension may perform many of the same tasks, you might want to consider restructuring your code. Specifically, consider the following:

  • Implement your core services in a private shared framework. A private shared framework lets you define your core services in one code module and link the code dynamically into your app and your Intents extension. Using a framework minimizes the size of both executables and ensures that both use the same code.

    For more information, see Embedding Frameworks In An App.

  • Use a shared container to store common resources. Put relevant images and data files into a shared container so that they can also be accessed by your Intents extension. You can enable shared container support in the Capabilities tab of your app and Intents extension targets.

    For more information, see Configuring App Groups in App Distribution Guide.

Testing Your Extension

Xcode supports launching your Intents extension directly from your Xcode project and debugging it while it runs in the simulator or on a device. To run and debug your Intents extension, do the following

To run and debug your Intents extension
  1. Select the build scheme for your Intents extension.

    When you add an Intents extension to your project, Xcode automatically creates a build scheme for running that extension.

  2. Select the target (simulator or device) for executing your code.

  3. Select Product > Run to begin your debugging session.

  4. When prompted by Xcode, select Siri (or Maps) as the app to run.

    Xcode builds your app and extension, installs them on the device, and launches the app you selected.

When installing your extension for the first time, Siri may not immediately recognize your app extension. You may need to wait several minutes before you can issue any relevant commands. Similarly, when updating your Info.plist file, you may need to wait several minutes before Siri recognizes any changes.

Using the Intents Framework From Your App

In iOS, your app must use portions of the Intents framework to perform specific tasks:

  • Use the INVocabulary class to register user-specific vocabulary terms. Register user-specific vocabulary only for terms that are specific to a single user of your app and that Siri might require help in understanding; do not register common or easily understandable terms. For information about registering vocabulary, see Specifying Custom Vocabulary.

  • Use the INPreferences class to ask the user for permission to handle intents; see Requesting Siri Authorization in Your App.

  • Create INInteraction objects when you want to donate interactions to the system. Donating interactions lets you provide context about what the user was doing. The system and other apps can use that information to improve search results and provide a better user experience. For more information, see INInteraction Class Reference.

Internationalization and Siri

Users can set different languages for Siri and for their device. Siri’s language is set using Settings > General > Siri > Language. The device’s language is set using Settings > General > Language & Region. Do not assume that these languages are the same.

When implementing your Intents extension, always return content using the device’s current language setting. If your app shares localized content with your extension, always provide that content in the device’s current language. Do not specify localized resources using Siri’s language.

For more information about localizing your app and Intents extension, see Internationalization and Localization Guide.