oracle.maf.api.platform.ios

Class SiriIntegration

Object

oracle.maf.api.platform.ios.SiriIntegration

public class SiriIntegration
extends Object

Integration methods for utilizing Siri shortcuts

Siri is available only on iOS devices running iOS 12.0 or later.

This class provides APIs that enable integration of Siri with a MAF application.

There are several ways that Siri shortcuts can utilized:

Siri Shortcut Suggestions

An application may provide Siri shortcut suggestions programatically. These shortcuts are exposed in the Siri section of the application's entry in the iOS Settings application. Users can opt to enable these shortcuts and record a voice phrase used to invoke them.

Add to Siri

A shortcut can be created and directly added within the application using the native Siri user interface. These are typically exposed with an "Add to Siri" button or similar action to allow the triggering of an action through a phrase spoken to Siri.

Donating Shortcuts

Shortcuts can be donated to the operating system when a user performs a particular activity. Donating shortcuts allows the OS to predict display the shortcut in Siri search results, the lock screen, and on the Siri watch face. Users may also record voice phrases to invoke donated shortcuts directly.

Donated shortcuts should be configured with a persistent identifier. They can be deleted using that persistent identifier should they no longer be relevant, for example if they are a shortcut to something that is no longer available.

In all cases, when a user invokes a shortcut the app is launched or foregrounded if already running and the shortcut is delivered through the MAF event system. Applications can listen for these shortcuts and perform appropriate action when they are invoked by the user.

Integration with Siri requires the explicit authorization by the user. Always use the requestSiriPermission API and validate the authorization prior to using any other Siri related API.

Refer to the SiriDemo public sample for examples on how to configure and use Siri within a MAF application.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SiriIntegration.SiriAuthorizationStatus Constants indicating the authorization status of Siri
static class	SiriIntegration.SiriEditShortcutStatus Constants indicating the result of editing a siri shortcut

Constructor Summary

Constructors

Constructor and Description
SiriIntegration()

Method Summary

Modifier and Type	Method and Description
static void	addToSiri(SiriShortcut shortcut) Add a siri shortcut Use this API to respond to a user invoked action, such as a "Add to Siri" button within the application.
static void	deleteAllShortcuts() Remove all donated shortcuts
static void	deleteShortcut(String persistentIdentifier) Remove a Siri shortcut with the specified persistent identifier
static void	donateShortcut(SiriShortcut shortcut)
static void	editWithSiri(String systemIdentifier, java.util.function.Consumer<SiriIntegration.SiriEditShortcutStatus> callback) Edit an existing shortcut Editing involves displaying a native dialog that allows the user to re-record the phrase used to invoke the shortcut.
static java.util.List<SiriShortcut>	getSiriShortcuts()
static void	requestAuthorization(java.util.function.Consumer<SiriIntegration.SiriAuthorizationStatus> callback) Request authorization to utilize Siri This method should be invoked and result handled appropriately prior to any use of Siri related methods.
static void	setSiriShortcutSuggestions(java.util.List<SiriShortcut> siriShortcuts) Set Siri shortcut suggestions To suggest shortcuts for actions that the user hasn’t performed in your app but may want to add to Siri, call setSiriShortcuts passing in a list of suggested shortcuts.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SiriIntegration

public SiriIntegration()

Method Detail

requestAuthorization

public static void requestAuthorization(java.util.function.Consumer<SiriIntegration.SiriAuthorizationStatus> callback)

Request authorization to utilize Siri This method should be invoked and result handled appropriately prior to any use of Siri related methods. If this is the first time Siri has been requested, the user may be prompted to allow Siri usage. Subsequent requests may not involve any user facing dialogs or prompts. On iOS, the supplied callback will be invoked asynchronously on the specified callback with the authorization status once determined. On all other platforms, the callback will be invoked inline with the value RESTRICTED. It is recommended that consumers determine the platform upstream and do not use Siri related methods when not on iOS version 12 or later. Callbacks are run within the context of the calling feature.

Parameters:

callback - the callback invoked with the authorization status once determined

getSiriShortcuts

public static java.util.List<SiriShortcut> getSiriShortcuts()

setSiriShortcutSuggestions

public static void setSiriShortcutSuggestions(java.util.List<SiriShortcut> siriShortcuts)

Set Siri shortcut suggestions To suggest shortcuts for actions that the user hasn’t performed in your app but may want to add to Siri, call setSiriShortcuts passing in a list of suggested shortcuts. The user views the suggestions under the Siri & Search section of the Settings app. Changes to the list of shortcut suggestions don't effect shortcuts that the user added to Siri.

Parameters:

siriShortcuts - the suggested siri shortcuts

addToSiri

public static void addToSiri(SiriShortcut shortcut)

Add a siri shortcut Use this API to respond to a user invoked action, such as a "Add to Siri" button within the application. A shortcut added will invoke an iOS provided UI allowing the user to customize and record the phrase used to invoke

editWithSiri

public static void editWithSiri(String systemIdentifier,
                                java.util.function.Consumer<SiriIntegration.SiriEditShortcutStatus> callback)

Edit an existing shortcut Editing involves displaying a native dialog that allows the user to re-record the phrase used to invoke the shortcut. The user may also delete the shortcut from the presented dialog. The user may cancel the presented UI without making any channges. If the provided system identifeir is invalid or the user is not on iOS, the callback will be invoked with the INVALID_SYSTEM_IDENTIFER value.

Parameters:

systemIdentifier - The system identifier associated with the shortcut to edit

callback - An optional callback invoked asynchronously on the calling feature with the result of the edit

donateShortcut

public static void donateShortcut(SiriShortcut shortcut)

deleteShortcut

public static void deleteShortcut(String persistentIdentifier)

Remove a Siri shortcut with the specified persistent identifier

Parameters:

systemIdentifer - The persistent identifier of the shortcut

deleteAllShortcuts

public static void deleteAllShortcuts()

Remove all donated shortcuts