Donate intents and expand your app’s presence

What are intents?

• a way of representing, in detail, a type of action that your app can perform

• Siri includes a lot of built-in intents that support a range of capabilities that you can use to integrate with the system (e.g., messaging, ride booking, payments)

• support the ability for you to define your own custom intents for use with Shortcuts

What are intent donations?

• An intent donation is the act of telling the system when a person performs an action in your app

• The system will store these donations and use them to expand your app’s capabilities and presence throughout the system

• Apps that donate intents show up in places throughout the system like Suggestions, Shortcuts, Focus, Smart Stack, and Siri

The life of an intent donation

1. Create a new intent definition:

• With your project open, create a new file of type SiriKit Intent Definition File

• in the following menu select any targets that I want to use the custom intent

1. Define the intent

• After selecting the new Intent file, click the + button on the bottom right and select New Intent (or Customize System Intent if your intent matches one of the existing built-in system intents)

1. Define eligibility

• After naming your intent in step two, check whether you’d like your intent to be eligible for widgets/shortcuts/(Siri)suggestions

1. Define Intent parameters

• These parameters are the input of your action/intent, which depend on your specific intent

• For each parameter you can select the type (String/Location/URL… can be custom, too)

• If the parameter options are not static and/or need to be provided by the app, check the Dynamic Options - this

The system reads the intent definition file to determine the intent and parameter combinations that an app supports for prediction.

1. Donate the intent when appropriate

• Create an instance of the intent class (this is automatically generated for you from the Intent file via an Xcode rule)

• donate it

// Donate your intent.

let intent = CheckWeatherIntent()
intent.location = weatherLocation

let interaction = INInteraction(intent: intent, response: nil)
interaction.donate { (error) in
  // Handle the error.
}

• It’s important to delete donations so people don’t get suggestions for actions in your app that are no longer relevant:

// Donate your intent.
let interaction = INInteraction(intent: intent, response: response)
interaction.identifier = "68753A44-4D6F-1226-9C60-0050E4C00067"
interaction.groupIdentifier = "san-diego"
interaction.donate { (error) in
  // Handle the error.
}

// Delete individual donations.
INInteraction.delete(with: ["68753A44-4D6F-1226-9C60-0050E4C00067"]) { (error) in
  // Handle the error.
}

// Delete group donations.
INInteraction.delete(with: "san-diego") { (error) in
  // Handle the error.
}

Behind the scenes

• the system stores these donations over time along with the context the person was in when the intent was donated

• As the user continue to repeat the same action, the app continues to make intent donations

• The system uses the intent parameters to determine whether the intents are equivalent or not

• The system uses machine learning and on-device intelligence to find patterns in the data and predict what intent is relevant given a person’s current context and past behavioral patterns

• The on-device intelligence integrates with user-facing features to expose your app’s capabilities and presence to the user

• all of the machine learning and intelligence is performed on-device in a privacy-preserving manner, meaning Apple does not collect any data that can be used to personally identify a user

What makes a great donation?

• Represents an action likely to be repeated by the user

• Intent payload is consistent across donations - so that a pattern can be recognized by the on-device intelligence

• No timestamps (in the suggestion parameters)