Article

Creating an Intents App Extension

Add and configure an Intents app extension in your Xcode project.

Overview

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

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

Enable the Siri Capability

Enabling the Siri capability adds a set of entitlements to your app. The App Store requires the presence of these entitlements for any iOS app or watchOS app containing an Intents extension.

  1. Open your app project in Xcode.

  2. In the project settings, select the appropriate target. For iOS, select your iOS app target. For watchOS, select your WatchKit Extension target.

  3. Select the Capabilities tab.

  4. Enable the Siri capability.

Figure 1

Enabling the Siri capability in your project

Enabling the Siri capability in your project

Add an Intents App Extension to Your Project

Adding an Intents app extension 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.

  1. Open your existing app project in Xcode.

  2. Choose File > New > Target.

  3. Select Intents extension from the Application Extension group of the iOS or watchOS platform.

  4. Click Next.

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

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

  7. Click Finish.

Figure 2

Adding an Intents app extension to your Xcode project

Adding an Intents app extension to your Xcode project

Specify the Intents that Your Extension Supports

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.

  1. In Xcode, select the Info.plist file of your Intents app 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 your extension handles. Set the value of each item to the class name of the intent.

  4. In the IntentsRestrictedWhileLocked key, 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.

Inclusion of the IntentsRestrictedWhileLocked key is optional in iOS. You use it to augment the list of intents that require an unlocked device. Some intents, such as those involving financial transactions, always require the user’s device to be unlocked. For those intents, Siri automatically asks the user to unlock the device, regardless of whether you include it under the IntentsRestrictedWhileLocked key. In watchOS, all intents require the device to be unlocked.

When a user’s 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. See the reference documentation for information about any special requirements.

Test Your Intents App Extension

Xcode supports launching your Intents app 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:

  1. Select the build scheme for your Intents extension. Xcode automatically creates a build scheme for you when creating your Intents extension target.

  2. Select the target (simulator or device) on which to run your code.

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

  4. When prompted by Xcode, select Siri or Maps as the main app to run. Xcode builds your app and extension, installs them on the devices, and launches the app you selected.

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

See Also

Siri Intents

Structuring Your Code to Support App Extensions

Move your back-end services to a private framework so your app and app extensions can use them.

Dispatching Intents to Handler Objects

Provide SiriKit with an object capable of handling a given intent.

Resolving and Handling Intents

Resolve, confirm, and handle user requests for your app’s services.

protocol INIntentHandlerProviding

The interface for dispatching intents to the custom objects that handle those intents.

Extension-Related Classes

Learn about the classes you use to build your Intents extension.