Over Christmas, I built an iOS and WatchOS app to track the tram times in Manchester. Tram Times seemed like the perfect candidate to try out the new api. Tram Times lets you add your favourite stations to your phone and watch, and requests the latest times from the Manchester public trams api when you need them. It is a simple app, but I really concentrated on a user being able to get the information they needed quickly. I achieved this by providing a simple interface in the app, Today Extensions and app shortcuts for a quick look. The ability to ask Siri for the next tram seemed like a no-brainer.

What seems more intriguing, is the off-product discovery available through Siri Suggestions. Using the new Intents api you can donate an Intent from your app every time the user performs an action you want Siri to know about. Siri will use the time/day, location and modality (walking, sitting, running) to suggest this action to you again at the most appropriate time. For Tram Times, Siri would use what it’s learnt about your usage to suggest you view the times in the morning when you catch it to work, or when you reach the location of your tram station when going home.

Designing Intents

To start donating Intents you need to add a new file called an intent definition file to your project.

Once added you can start creating your Intent. You want to select a category for your Intent such as View, Download or Order. Different categories can present different UI when the shortcut is activated for instance View will show just the shortcut whereas download will show the progress of your download. I have selected the Information category View as I want the user to be able to view the latest tram times with this intent.

Enter the title for your intent and a description. You can decide here whether you want the user to confirm the intent (useful for orders). Define parameters that you want to use in your intent when you handle it. Here I have chosen my custom model type of Station. This is the station that the user will want to view the tram times for.

If you have multiple parameters you can define the combinations that are supported below. You can then define the Title and Subtitle of your intent; these will be displayed to the user when your shortcut is suggested by Siri.

If your action can run in the background then you need to check the option for ‘Supports background execution’. Once you have defined your intent, you need to select the options in Target membership to have Xcode generate your Intent classes for you.

It helps if your classes can be generated in the target where your action is performed. This will be easier if your project’s main actions are separated into their own frameworks. Here I have separated all of my app’s data requests into my own custom framework ‘Station Request’. I generate my Intent classes in this framework as this is where I want to donate the intent.

Donating Intents

Wow that was a lot of setup! Now, let’s write some code.

Make sure you import Intents into the file used. Here I add an extension to my Station model code.

If your project is supporting previous operating systems then you will need to annotate the Intent code you use with @available.

If your intent code has been generated correctly in your framework, you will be able to use it here, ViewStationIntent. Create a new Intent and assign an INObject to your custom object parameter. Give it an identifier you will be able to handle later; I give it the station identifier. You also need to provide the name which will be shown for the custom object in the Siri Suggestion.

Here you can provide a suggested invocation phrase, which will be given to the user if they try to customise an invocation phrase for your intent.

Calling this function before I request new tram times for a station it will donate an intent for me:

Again making sure that I import Intents, iOS12 is available to use the Intents apis.

Create an INInteraction using the intent we have just created. Then call donate. Siri will pick this information up and should start suggesting this action to your users when you are in a similar situation.

You can debug this and make sure your intent is donated correctly by turning on the developer options. This will show your recently donated shortcuts on the lock screen.

If you are having problems, look at the error you received when donating the interaction.

You can now add a custom phrase for this shortcut in the Siri & Search page in settings. It didn’t seem to work for me in iOS12 beta 1; I had to wait for beta 2 to be able to save the shortcut phrase.

Handling Shortcuts

Once a user follows your shortcut, you will need to handle it in your App Delegate.

The userActivity contains the interaction you donated in the previous section. You can unwrap this and cast it into your custom Intent. I used this to get my station identifier back and can use it to request the latest tram time. This lets me open the app on the correct station page.

Conclusion

In this first part I have shown you how to use the new Siri Intents api. In my next article I’ll show how to use Intent Extensions and Custom Intent Responses to respond to the user inline with Siri.

Look at my full implementation here:

Winnie90/TFGMLive

I’m still going to be working on tidying it up and more work with the Siri watch face.

Thanks for reading! If you’re inspired, here are some useful links to help if you get stuck:

• Introduction to Siri Shortcuts - WWDC 2018 - Videos - Apple Developer
• Accelerating App Interactions with Shortcuts
• Custom Intents with SiriKit on iOS 12