Guides and Sample Code

Developer

SiriKit Programming Guide

On This Page

App Vocabulary File Format

Apps with custom terminology can include a AppIntentVocabulary.plist file in their app’s bundle to help Siri understand how that terminology is meant to be used. This property-list file includes the specific terms that users of your app will understand, along with pronunciation guidelines and examples of how they might be used. This file defines terms that apply globally to all users of your app.

You can include localized versions of your vocabulary property list file in the language-specific project (.lproj) directories of your app. When you submit your app to the App Store, your AppIntentVocabulary.plist file and any localized versions of that file are sent to Siri for processing. The content of those files remains on the server and that content is specific to that app version.

Table 8-1 lists the keys you include in your AppIntentVocabulary.plist file. Make these keys children of the Root dictionary entry.

Table 8-1Root-level keys

Key

Type

Summary

ParameterVocabularies

Array of Dictionary

(Optional) The terms that correspond to specific properties of your app’s supported intents; see Parameter Vocabularies.

IntentPhrases

Array of Dictionary

(Optional, but recommended) Example phrases that can be shown in the Siri guide, and which Siri uses for learning your app’s terminology; see Intent Phrases.

Parameter Vocabularies

ParameterVocabularies key (Array - Optional) Contains an array of dictionaries, each of which defines a set of terms and the intent properties to which those terms apply.

Each dictionary contains two required keys, which are listed in Table 8-2.

Table 8-2Parameter vocabularies keys

Key

Type

Summary

ParameterNames

Array of String

(Required) The properties to which the specified vocabulary terms apply; see Parameter Names.

ParameterVocabulary

Array of Dictionary

(Required) The vocabulary terms, including any pronunciation and examples; see Parameter Vocabulary.

Parameter Names

ParameterNames key (Array - Required) An array of strings, each of which contains the intent class and property name to which the vocabulary values apply. The format for each string is <intent>.<property>, where <intent> is the name of the intent class and <property> is the name of a resolvable property of that class. You can configure custom vocabulary for the following properties in the global vocabulary file:

  • INRequestRideIntent.rideOptionName

  • INStartWorkoutIntent.workoutName

  • INPauseWorkoutIntent.workoutName

  • INResumeWorkoutIntent.workoutName

  • INEndWorkoutIntent.workoutName

  • INCancelWorkoutIntent.workoutName

Parameter Vocabulary

ParameterVocabulary key (Array - Required) An array of dictionaries, each of which contains a custom term that can be used for a given parameter.

Each dictionary contains two required keys, which are listed in Table 8-3.

Table 8-3Keys for a single vocabulary entry

Key

Type

Summary

VocabularyItemIdentifier

String

(Required) The string that Siri provides to your code when it recognizes the custom term; see Vocabulary Item Identifier.

VocabularyItemSynonyms

Array of Dictionary

(Required) The defined phrase for Siri to recognize, including pronunciation and examples; see Vocabulary Item Synonyms.

Vocabulary Item Identifier

VocabularyItemIdentifier key (String - Required) The string that you want Siri to assign to the identifier property of the INSpeakableString object used to populate the intent. The string itself is never seen by the user and should not be localized. In fact, the same identifier string should appear in each of the localized versions of your vocabulary property list file.

This identifier string applies to all synonyms listed in the Vocabulary Item Synonyms portion of this parameter entry.

Vocabulary Item Synonyms

VocabularyItemSynonyms key(Array - Required) An array of dictionaries, each of which defines a custom phrase that the user might employ for your app. Each synonym entry may also contain pronunciation guidelines and examples of how the phrase might be used. All synonyms in the array are associated with the same Vocabulary Item Identifier key.

Each dictionary may contain the keys listed in Table 8-4.

Table 8-4Synonym keys

Key

Type

Summary

VocabularyItemPhrase

String

(Required) The custom phrase spelled in the same way that your app uses it; see Vocabulary Item Phrase.

VocabularyItemPronunciation

String

(Optional) Pronunciation hints for the phrase, formatted in a “sounds like” format; see Vocabulary Item Pronunciation.

VocabularyItemExamples

Array of String

(Optional) Examples of how the phrase might be used; see Vocabulary Item Examples.

Vocabulary Item Phrase

VocabularyItemPhrase key (String - Required) The localized phrase for Siri to recognize and display. Specify this term or phrase exactly as it should appear in the Siri interface.

Vocabulary Item Pronunciation

VocabularyItemPronunciation key (String - Optional) A version of the phrase that sounds the same when read in the native language. This is not a phonetic spelling of the original phrase, but is a string that has an equivalent sound when spoken. For example, the phrase “iTunes” could be have “eye toons” as its pronunciation string. Siri uses these strings as hints when listening to the user and speaking the phrase.

Vocabulary Item Examples

VocabularyItemExamples key (Array - Optional) An array of strings containing examples of the phrase used in context. Include examples that are typical and succinct by paring each example down to the smallest string that includes the phrase. You can specify more complex examples of your terminology using the top-level Intent Phrases key.

Intent Phrases

IntentPhrases key (Array - Optional) Contains an array of dictionaries, each of which contains the sample phrases that a user might speak in relation to one of your app’s intent. Siri uses your examples as hints to help it understand your app’s terminology better. Each sample phrase or group of phrases must have an associated intent class, which helps Siri identify the user’s intention more readily.

Each dictionary in the array has two required keys, which are listed in Table 8-5.

Table 8-5Intent phrase keys

Key

Type

Summary

IntentName

String

(Required) The name of the intent class to which the examples apply; see Intent Name.

IntentExamples

Array of String

(Required) The phrases that the user might speak in relation to the specified intent; see Intent Examples.

Intent Name

IntentName key (String - Required) Specifies the name of the intent class to which each phrase applies. For example, you might specify the strings “INRequestRideIntent” for sample phrases involving the booking of a ride.

Intent Examples

IntentExamples key (Array - Required) An array of strings, each of which contains a sample phrase that a user might speak. Sample phrases may be as complex as needed, but should reflect actual phrases users might say when using your app. Your examples may include any custom terminology that you define using the Parameter Vocabularies key. Sample phrases when booking a ride with an app called CharityTruck might include the following:

  • "Ask CharityTruck for a ride to the Red Cross on 3rd and mission.”

  • "Check with CharityTruck if I can get a hauler truck tomorrow.”

  • "See if CharityTruck can send a pickup truck to my house at 7am tomorrow.”

Rules for Localized Vocabulary Pronunciation

For specific localizations, additional rules apply when specifying values for the Vocabulary Item Pronunciation key:

  • zh_CN: China Mandarin localization

    • Tones are represented using the numbers 1, 2, 3, 4, and 5. Use the number 5 for the neutral tone. Place tones at the end of the Pinyin representation of each character. For example, “ping2 guo3”.

    • You can replace the special character “ü” in Pinyin with “yu”. For example, “nü” would become “nyu”.

  • zh_TW: Taiwan Mandarin localization

    • Tones are represented using the numbers 1, 2, 3, 4, and 5. Use the number 5 for the neutral tone. Place tones at the end of the Pinyin representation of each character. For example, 蘇打綠 becomes “su1 da3 lyu4”.

  • zh_HK: Hong Kong Cantonese localization

    • Use the Jyutping 粤语拼音 (粤拼) romanization system for Cantonese.

    • Tones are represented using the numbers 1, 2, 3, 4, 5, and 6. Place tone numbers at the end of the Jyutping. For example, 的士 becomes “dik1 si2”, and 短訊 becomes “dyun2 seon2”.

Example

Figure 8-1 shows a sample vocabulary file that defines a custom term for a workout regimen in the app CardioBonanza. When the user speaks the term “Cardio Craze” in relation to that app, Siri knows to put the string cardio_craze_workout in the workoutName property of the INStartWorkoutIntent object. When processing the intent, the CardioBonanza app uses that string to start the specific workout.

Figure 8-1A global vocabulary file for a fitness app image: ../Art/app_intent_vocabulary_2x.png