Design App Intents for system experiences

Hi, my name is Ray and I'm a designer on the Apple design team. Today we'll cover how you can design great app intents.

From setting a 5 minute timer in spotlight, to running a shortcut to create a new freeform board.

App intents surface app functionality to the system outside of your app. In addition to spotlight, app intents open your app to system experiences, Including the action button, squeeze, widgets, controls, and Siri.

App intents also appear as actions in the Shortcuts app, where people can explore, remix, and add them to create their custom shortcuts.

There are currently hundreds of app intents from many apps, and here are just a few that have unlocked new experiences in the system beyond their app.

With these app intents, you can create experiences across the Apple ecosystem that do more than ever before. But what does an app intent look like? Let's take a look at a finder app intent in shortcuts.

An app intent consists of a summary of what it does, which starts with the app, followed by a verb, and includes the parameters that people need to fill out before the intent is run.

App intents can be combined with other intents into shortcuts in novel ways, to create powerful new flows that they could not do alone. And with that, we have updated guidance on how you should design your app intents to work well across all of these experiences. We'll start with which functionality you should surface from your app. Then we'll get into the details on how to structure your app intents.

Let's start with which app intents to make. Previously, app intents were meant to be the most habitual tasks in your app that could be useful outside of your app. This meant an app was expected to only have a few app intents. In iOS 18, we're changing this guidance to go beyond common functionality.

Now, anything your app does should be an app intent.

If you're creating app intents for the first time, you can still prioritize the most common habitual functionality in your app. However, it's important to keep in mind that there is a balance between a rich set of flexible app intents and unclear brittle app intents. To start, here are a few distinct types of intents. You'll find in the shortcuts app. Intents that start with these verbs are fundamental types of intents that you should start with when you're deciding which types of functionality in your app to surface in app intents.

Next, avoid making several different intents for the same task. For example, if you're thinking about creating several app intents for opening different reminders, don't make one for each type of the same functionality.

Instead, structure your app's functionality into a flexible intent, where the reminders are contained in the parameter.

Another point to keep in mind is to avoid making app intents for specific UI elements. App intents should not exclusively trigger specific UI elements, such as tapping a cancel button, or swiping down on a platter. This is not expected, because it hides the task of the intent, resulting in unexpected behavior.

Instead, make app intents that represent the underlying task people normally access using these UI elements, such as saving a draft or deleting a draft.

Additionally, if your app supports live activities, audio playback, or recording, read app intents that make it possible to do these things from the background. This is great for simple intents that don't require further in app action. Now let's talk about how to structure your app intents, starting with parameter types. As we saw earlier, an app intent contains a parameter summary, which contains the inputs that your intent uses to run the task. For example, this camera intent opens your camera to a specific camera mode.

Since the parameter can be changed to any of these camera modes, it's important to make sure the summary is always readable as a sentence, regardless of which mode you select.

Parameter summaries are essential for people to understand what your app intent does when exploring in a shortcut store, while also maintaining readability when they configure the parameter. If your intent needs input, such as picking a number or entering text, choose from our library of built-in parameters. These are best for simple tasks, such as adding a date to a reminder.

And if your parameter needs to contain options, that are not covered by the basics. Such as opening one of the tabs in your app. Use a static parameter to contain those tab options. The tab parameter now contains each of these tabs. If you have a parameter with options that change over time, such as including more notes folders, when someone adds them to the app. Create an app entity as a dynamic parameter to ensure this is updated with new options over time.

When a parameter is optional, the intent will not ask follow up questions if you don't specify them up front. This behavior is preferred. For example, let's look at this notes app intent. It shows a folder in notes that you select.

If you ran this intent, but you did not set a folder to open to, it will just open your notes to the folder's view, providing the full folder picking experience, instead of asking you which folder you want to open every time you run the intent.

Optional parameters are great, because they allow your app intent to take action immediately, even if someone has not configured the parameter. However, if you feel your app intent is not helpful at all, unless the parameter is asked for every time, you can set it to "required." For example, a search mail intent requires the text input to be of any use. In this case, the text parameter is required.

This means that every time someone runs your app intent, they will be asked a follow up question that you write. Keep these questions concise and clear, like the one you see here.

Now, let's take a look at how you should structure an intent that changes the state that only has two states.

For example, flashlight has an app intent called set flashlight, which is an intent that sets the flashlight on or off. Because the intent would only change between these two states, the intent should also support toggle as the default parameter.

If you did not support toggle as a default parameter, every time someone runs the intent, they'll be asked to choose between turning the flashlight on or off.

Instead, providing the toggle as default allows the intent to turn on or off the flashlight without needing to ask.

Next, let's talk about when to open your app as part of your intent. Previously, app intent avoided opening apps into the foreground unless necessary.

In iOS 18, opening your app is now a common behavior to show people that the intent has made a change in the app.

Returning an open as part of your app intent gives people the option to see the change. There are two ways your app is opened as part of using an app intent. The first is if your app intent inherently functions to open to a particular view. For example, this clock app intent opens the stopwatch.

When the intent is run, it opens the clock app to the stopwatch. If this is the case, you should conform your app intent to open intent as it inherently functions to open your app.

The second case is if your app intent completes with a change in the app UI or shows search results. For example, if you have a create freeform board intent, it should finish running by opening the app to show that the new board was created.

By opening the app directly to the new board in the app without any additional in app animations, you can quickly get started on your new freeform board. This behavior appears in the intent as an open when run toggle, which is default on. This gives people the choice to toggle off this behavior if they want to use your intent as part of a shortcut that does several things where they might want several intents to run without opening each app in the flow.

Now you know the latest guidance on making great app intents. To recap, design powerful app intents that contain tasks that your app can do. Structure intents to be flexible and readable across many configurations and use cases.

And lastly, give the option to toggle binary parameters or open your app when appropriate.

To learn more about app intents, check out these talks.

Thank you. And we can't wait to see your app intents.