Guides and Sample Code

Developer

SiriKit Programming Guide

On This Page

Specifying Custom Vocabulary

Apps that have custom vocabulary should inform Siri about the proper usage of that vocabulary. Custom vocabulary refers to any terms that Siri might not inherently understand. For example, a ride booking app that refers to a specific vehicle type as a “Vroom” could define that term and provide examples of how it might be used. Defining custom vocabulary helps Siri understand commands used in conjunction with your app, which improves the user experience.

There are two ways to define your app’s custom vocabulary:

  • To register terms that are specific to a single user, use the INVocabulary object in your iOS app.

  • To register terms common to all users of your app, add a global vocabulary file to your iOS app.

The terms you define from your iOS app are automatically shared with your Intents extension on watchOS. You do not need to register your user-specific or global vocabulary again from your Intents extension on watchOS.

In addition to defining any custom terms, you use the global vocabulary file to provide Siri with sample phrases for each of your app’s supported intents. Siri displays your sample phrases in the Siri guide, which users can read to learn how to invoke your app’s services.

Registering User-Specific Vocabulary Terms

Use the shared INVocabulary object to register vocabulary that is specific to a single user. User-specific terms must belong to one of the following categories:

  • Contact names (only if they are not managed by the Contacts framework)

  • Contact groups

  • Photo tags

  • Photo album names

  • Workout names

  • Vehicle profile names (CarPlay only)

  • Car names

  • Payment organization names

  • Payment account nicknames

When selecting the vocabulary to register, choose terms that could be misunderstand by someone not familiar with your app. Do not register terms that are easily understood, such as “My Photo Album” or “My Workout”. Instead, focus on terms whose literal meaning differs from your app’s usage of those terms. For example, a messaging app might register the screen names from the user’s favorites list.

To register terms, use the setVocabularyStrings:ofType: method of the INVocabulary object. Each group of terms you register must be associated with a specific category. Registering a new set of terms replaces the previous terms for that category, so include all of the terms you need each time you call the method. The most important terms should always be first in the NSOrderedSet object that you create.

Listing 4-1 shows an example that registers a set of custom workouts. The app sorts the workout names based on the last time they were used, placing the most recently used workouts first in the ordered set. Typically, you register user-specific terms from your app, instead of from your Intents extension.

Listing 4-1Registering user-specific vocabulary

Objective-C

  1. NSOrderedSet* workoutNames = [self sortedWorkoutNames];
  2. INVocabulary* vocabulary = [INVocabulary sharedVocabulary];
  3. [vocabulary setVocabularyStrings:workoutNames
  4. ofType:INVocabularyStringTypeWorkoutActivityName];

Swift

  1. let workoutNames = self.sortedWorkoutNames()
  2. let vocabulary = INVocabulary.shared()
  3. vocabulary.setVocabularyStrings(workoutNames, of: .workoutActivityName)

For additional information about registering user-specific vocabulary terms, see INVocabulary Class Reference.

Creating the Global Vocabulary File

Use a global vocabulary file to specify sample phrases for using your app and to register terms that are common to all users of your app. All apps should provide at least a few sample phrases, and Siri displays those phrases in the Siri guide as examples of how to engage your app. If your app employs custom terminology that applies to all users of the app, you can also declare that terminology in your global vocabulary file.

Global terms must belong to one of the following categories:

  • Ride options

  • Workout names

A global vocabulary file is a property list file with the name AppIntentVocabulary.plist that you include in your app’s bundle. Place the initial version of this file in the .lproj directory corresponding to your app’s base development language. Include localized versions of the file in each of your app’s language-specific project (.lproj) directories. In Xcode, you can create localized versions automatically from the File inspector.

To create the global vocabulary file
  1. Select New > File.

  2. In iOS > Resource, select the Property List file type.

  3. Click Next.

  4. Set the name of the file to AppIntentVocabulary.plist.

  5. Click Create.

  6. Select the AppIntentVocabulary.plist file in your project.

  7. Add two keys under the Root element.

    • Set the name of the first key to ParameterVocabularies.

    • Set the name of the second key to IntentPhrases.

  8. Configure the remaining keys as described in App Vocabulary File Format.

The global vocabulary file contains two keys at the root level:

  • The ParameterVocabularies key defines your app’s custom terms and the intent parameters to which they apply.

  • The IntentPhrases key contains example phrases for invoking your services. If you define custom terms for your app, at least some of your sample phrases should show how to use those terms.

Terms must be associated with a specific property of an intent object. When Siri hears a custom term, it uses that term to fill in the corresponding property in the intent object. (Specifically, it assigns the identifier you provide for that term to the property.) You may associate the same term with multiple intents. For example, a custom workout name would apply to all of the workout-related intents.

For detailed information about the structure and keys of the global vocabulary file, see App Vocabulary File Format.