Siri Shortcuts

[mattbarker016]

Goal

Using the below methods, create a way to allow users to engage with their favorite routes using Siri.

We want to suggest Ithaca Transit routes contextual using time and location with the help of Siri, and as a bonus, be able to use Siri to select a route and start the app flow.

Here is the starting point for the SiriKit documentation. It's not the most well-structured, so if you get a bit lost in it, it's always helpful to start back here. I've included more specific links throughout this issue, too.

Tasks

0. Create a URL scheme for the app.
1. Donate shortcuts for user searches.
2. Define relevant shortcuts based on time and location.

0. Create a URL scheme for the app.

ithaca-transit://getRoutes?...

The parameters should be everything needed to open RouteOptionsViewContoller and perform Network.getRoutes(...). Within application(_ application: UIApplication, open url: URL, ...) in the AppDelegate, you will handle re-creating the navigation stack and starting the requests.

Resources AppCode Guide Apple Documentation

A Note We may want to create some simple documentation now that the iOS app has its own API. Exciting! Or extra work... eh I think it's kinda cool. But actually, if our other apps or student projects want to integrate with our solution, I'd love to have some documentation for it. It will make us look much more legitimate and standard with our competitors too!

1. Donate shortcuts for user searches

A donated shortcut is an app-specific action the user performs regularly and may want to perform again. ... Using signals like location, time of day, and type of motion (such as walking, running, or driving), the system can intelligently predict just the right time and place for the shortcut. The system can then offer the shortcut to the user through an iOS lock screen notification, Spotlight search results, media playback controls on the lock screen (for media playback shortcuts), or the Siri face on Apple Watch.

Donate an interaction documentation.

Instructions

Create New Target: File > New > Target IntentExtension Modify Intents.intentdefinition: You can create this file by going to File > New > File > Resource > SiriKit Intent Definition File. Open it, click the "+" button in the bottom left corner to create one and define values. Create Intent Handler Classes

//
// IntentsHandler.swift
//

class IntentHandler: INExtension {

    override func handler(for intent: INIntent) -> Any {
        switch intent {
        case is <Intent-Name>Intent:
            return <Intent-Name>IntentHandler()
        default:
            return self
        }
    }

}

class <Intent-Name>IntentHandler: INExtension, <Intent-Name>IntentHandling {

    func handle(intent: <Intent-Name>Intent, completion: @escaping (<Intent-Name>IntentResponse) -> Void) {
            completion(<Intent-Name>IntentResponse.success(...))
            // completion(<Intent-Name>IntentResponse(code: .failure, userActivity: nil))
    }

}

Using these classes and functions, add the donation code within the app once we have the relevant information (somewhere in Route Options). The code will look something like this:

let intent = <Intent-Name>Intent()
let interaction = INInteraction(intent: intent, response: nil)
interaction.donate(completion: { (error) in
guard let error = error else { return }
    print("Intent Donation Error: \(error.localizedDescription)")
})

2. Define relevant shortcuts based on time and location

A relevant shortcut is an app-specific action the user hasn't performed, that includes relevancy information like location and time of day. These shortcuts are presented intelligently at appropriate times and places on the Siri face on Apple Watch.

Instructions

Follow the documentation here.

Relevant Classes

• INDateRelevanceProvider: The provider class that specifies a relevant day and time.
• INLocationRelevanceProvider: The provider class that specifies a relevant location.

Important Note

Suggesting a shortcut is different from donating. From this page:

Shortcut suggestions are available to the user only in the Settings app under the Siri & Search section. This differs from donated shortcuts, which Siri shows to the user in places such as Spotlight search, Lock Screen, and the Siri watch face.

We don't want to do this presently: it's not very discoverable and we'd have to write more code to transition from suggested to donated.

[mattbarker016]

Slack me with any questions or anything!

[mattbarker016]

Update: We are going to create a Ithaca-transit:// URL scheme that takes in parameters used to calculate routes. The IntentHandler will use this to keep client implementation details from the Siri extension, and serves as a way to continue to develop the app's extensibility. Yana is on top of this, just updating this for posterity.