Tools to Donate Siri Shortcuts in iOS 12

Apple introduced Siri Shortcuts in iOS 12, allowing applications to expose their key actions to the system so Siri can suggest them or run them via custom voice commands. To facilitate this integration, Apple provides developers with two main programmatic approaches—NSUserActivity and custom Intents—along with dedicated Xcode modeling tools and device-level debugging utilities. This guide outlines the specific developer tools and frameworks used to donate shortcuts to Siri in iOS 12.

1. NSUserActivity API

The NSUserActivity class is the most lightweight tool for donating shortcuts. It is designed to capture actions that represent navigating to a specific screen or viewing content within an app.

To turn an activity into a shortcut donation, developers configure specific properties:

  • isEligibleForPrediction: Set to true to allow the system to predict and suggest the activity on the lock screen, Siri watch face, or Spotlight search.
  • isEligibleForSearch: Set to true to index the item for Spotlight search.
  • persistentIdentifier: Provides a unique identifier to update or delete indexed activities.
  • suggestedInvocationPhrase: Recommends a default voice trigger to the user.

Once configured, assigning the activity to a UIViewController's userActivity property or calling becomeCurrent() donates the action to Siri.

2. SiriKit and Custom Intents

For more complex actions that take parameters or perform background tasks without launching the app's full UI, iOS 12 introduced Custom Intents via the SiriKit framework.

Developers donate intents using the INInteraction class:

  • An intent instance (conforming to INIntent) is created and populated with relevant parameters.
  • The intent is wrapped in an INInteraction object.
  • Developers invoke the donate(completion:) method on the INInteraction instance to send the action and its context to the system.

3. Xcode Intent Definition File (.intentdefinition)

Xcode 10 introduced the SiriKit Intent Definition file, a visual authoring tool for building custom intents.

Key capabilities of the Intent Definition editor include:

  • Intent Configuration: Specifying the category, title, description, and default phrases.
  • Parameter Definition: Defining dynamic inputs for the shortcut, specifying data types, and setting whether parameters are required.
  • Code Generation: Xcode automatically generates native Swift or Objective-C classes representing the intent and its response, ensuring type safety when creating donations.
  • Background Execution Settings: Declaring whether the action can run in the background via an Intents App Extension or requires the primary app to launch.

4. iOS Developer Settings

To assist with verification and testing, iOS 12 includes dedicated shortcut debugging options directly within the device settings:

  • Located under Settings > Developer.
  • Display Donated Shortcuts: Displays shortcut donations directly in Search and the lock screen to verify that donations are actively reaching the system.
  • Display Recent Shortcuts: Surfaces recently donated shortcuts inside the Shortcuts app interface and Siri Settings, allowing developers to immediately test voice triggers and action execution without waiting for system heuristics to predict them.