Guides and Sample Code

Developer

SiriKit Programming Guide

On This Page

Creating an Intents UI Extension

When you handle an intent, Siri and Maps often display the details from the response object your Intents extension provided in a standard interface. If you want to add your own custom content to the standard interface, you must provide an Intents UI extension.

An Intents UI extension does not replace the Intents extension that you use to handle intents. It is a separate app extension that lets you customize how your response to an intent is presented to the user. You can use a custom interface to show additional details or to incorporate your app’s branding, which can provide a more familiar experience for the user.

You can provide an Intents UI extension if you are supporting intents in the following domains:

  • Messaging

  • Payments

  • Ride booking

  • Workouts

The main object in an Intents UI extension is a view controller, which you use to display your custom content. An Intents UI extension has only one view controller, so the view controller must be able to display content for any of the intents supported by the extension. You can create separate Intents UI extensions for each intent if you prefer.

Configuring Your iOS App Project

Use Xcode to configure the initial files for your Intents UI extension. When creating your Intents extension, you can ask Xcode to create an Intents UI extension at the same time. You can also add an Intents UI extension to your project separately at any time.

To add a new Intents UI extension to your app
  1. Open your existing iOS app project in Xcode.

  2. Select File > New > Target.

  3. Select Intents UI extension from the iOS Application Extension group.

  4. Click Next.

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

  6. Click Finish.

The template provided by Xcode contains a storyboard with a single view controller. Siri and Maps always load and display the initial view controller in your storyboard file, so configure that view controller with your initial content. You can include other view controllers in your storyboard if you plan to embed them as children in the initial view controller. You are responsible for managing all interactions between the initial view controller and any other view controllers in your storyboard.

The Info.plist file of your Intents UI extension lets SiriKit know which intents your extension supports. Table 5-1 lists the keys that must be included in the dictionary of the NSExtension key for your extension. Specify the intents that your extension supports in NSExtensionAttributes key.

Table 5-1Keys for the Info.plist file of an Intents UI extension

Key

Description

NSExtensionAttributes

The value of this key is a dictionary. This dictionary must contain an IntentsSupported key whose value is an array of strings. The value of each string is the name of an intent class that the extension supports. The configuration of this key is the same as for your Intents extension.

NSExtensionMainStoryboard

The value of this key is the name of the storyboard file containing your extension’s view controller. You may substitute the NSExtensionPrincipalClass key for this one if you prefer to initialize your view controller programmatically.

NSExtensionPointIdentifier

The value of this key must be the string com.apple.intents-ui-service.

To specify the intents that your custom interface 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.

  3. In the IntentsSupported key, add items for each intent you support. The type of each item must be String, and the value must be the class name of the intent.

For more information about the keys to include in the Info.plist file of your Intents UI extension, see Information Property List Key Reference.

Implementing Your View Controller

The initial view controller of your storyboard file displays your custom content. Before displaying any UI to the user, Siri or Maps load your view controller and call its configureWithInteraction:context:completion: method. Implement that method and use the provided interaction object to configure the contents of your view controller. The context parameter tells you where your view controller will be displayed, giving you an opportunity to display your content differently in Siri and Maps.

While onscreen, your view controller remains part of the foreground interface until the user dismisses the Siri or Maps interface. You may update your view controller’s interface as needed using timers or other programmatic means. Your view controller also receives the normal view controller callbacks when it is loaded, shown, and hidden. However, your view controller does not receive touch events or any other events while it is onscreen, and you cannot add gesture recognizers to it. Therefore, never create an interface with controls or views that require user interactions.

Figure 5-1 shows the high-level life cycle of your Intents UI extension and its view controller. The system creates your view controller and calls its configureWithInteraction:context:completion: method, passing it the interaction object you need to configure your interface. Once configured, your view controller is presented onscreen with the rest of the Siri or Maps content. While onscreen, your view controller can run animations and update itself using timers and other programmatic means, but it does not receive touch events or responder-chain events.

Figure 5-1Life cycle of an Intents UI extension image: ../Art/intentsui_lifecycle_2x.png

When the user dismisses the Siri or Maps interface, the system releases its reference to your view controller and your Intents UI extension. Your view controllers should only display information. Do not try to save data or communicate with your app when your view controller moves offscreen.

Here are some tips for implementing the view controller for your Intents UI extension:

  • Incorporate your brand into your interface. Using your app’s color, imagery, and other design elements is a great way to add familiarity and convey the presence of your app within the Siri or Maps interfaces.

  • Use child view controllers to switch between different types of content. Your Intents UI extension has only one main view controller. If you display different content for different intents, use child view controllers to manage the views that are relevant for that intent. In your configureWithInteraction:context:completion: method, install the child view controller based on the type of the intent object.

  • Configure any animated content to run only when your view controller is visible. Wait until your view controller’s viewDidAppear: method is called to start animations. Stop animations in your view controller’s viewWillDisappear: method.

  • Configure your view controller’s view as quickly as possible so that Siri can display it. Your view controller may not be onscreen for very long, so use local resources and the provided INInteraction object for the bulk of your configuration. If you need to fetch more information from a server, always do so asynchronously and update your interface later.

  • Configure your interface using only the provided interaction object. The provided INInteraction object contains the original intent and the response provided by your Intents extension, which runs in a separate process. Using only the provided interaction object ensures that your view controller’s interface accurately reflects the information provided by your Intents extension. To communicate more information to your Intents UI extension, your Intents extension can include a custom NSUserActivity object with its response and put the additional information in that object’s userInfo dictionary.

  • Do not include advertising in your interface. You may include branding and information that is relevant to the user, but advertising is prohibited.

  • Return a zero size when you want to hide your custom interface. When calling the completion block of the configureWithInteraction:context:completion: method, specify CGRectZero for the size when you do not want the view controller to be shown onscreen. You might hide the view controller when there is no additional information to display for the specified intent.

  • Do not include a map view when your view controller is shown in a Maps context. When the context parameter of the configureWithInteraction:context:completion: method is set to mapsCard, do not include an MKMapView in your view controller’s interface. Maps already displays a map, so having two maps showing similar information would be confusing to users.

For more information about configuring your view controller, see INUIHostedViewControlling Protocol Reference.

Replacing the Default Interface

For ride booking and message intents, you can hide the default content provided by the system if it conflicts with the content you provide. For message intents, Siri displays the message content and recipients. For ride booking intents, Siri and the Maps app display a map showing the user’s location. If you provide your own interfaces with the same information, use the properties of the INUIHostedViewSiriProviding protocol to suppress the display of the system interfaces.

For more information about suppressing the default map and message information, see INUIHostedViewSiriProviding Protocol Reference.