VoiceInteractionSession

KEY_FOREGROUND_ACTIVITIES

public static final String KEY_FOREGROUND_ACTIVITIES

Bundle key used to specify foreground activity app components.

Type: ArrayList<ComponentName>

Constant Value: "android.service.voice.FOREGROUND_ACTIVITIES"

KEY_SHOW_SESSION_ID

public static final String KEY_SHOW_SESSION_ID

Bundle key used to specify the id when the system prepares to show session. It increases for each request.

Type: int

Constant Value: "android.service.voice.SHOW_SESSION_ID"

SHOW_SOURCE_ACTIVITY

public static final int SHOW_SOURCE_ACTIVITY

Flag for use with onShow(Bundle, int): indicates that an Activity has invoked the voice interaction service for a local interaction using Activity#startLocalVoiceInteraction(Bundle).

Constant Value: 16 (0x00000010)

SHOW_SOURCE_APPLICATION

public static final int SHOW_SOURCE_APPLICATION

Flag for use with onShow(Bundle, int): indicates that the application itself has invoked the assistant.

Constant Value: 8 (0x00000008)

SHOW_SOURCE_ASSIST_GESTURE

public static final int SHOW_SOURCE_ASSIST_GESTURE

Flag for use with onShow(Bundle, int): indicates that the session has been started from the system assist gesture.

Constant Value: 4 (0x00000004)

SHOW_SOURCE_AUTOMOTIVE_SYSTEM_UI

public static final int SHOW_SOURCE_AUTOMOTIVE_SYSTEM_UI

Flag for use with onShow(Bundle, int): indicates that the voice interaction service was invoked from an Android automotive system UI.

Constant Value: 128 (0x00000080)

SHOW_SOURCE_NOTIFICATION

public static final int SHOW_SOURCE_NOTIFICATION

Flag for use with onShow(Bundle, int): indicates that the voice interaction service was invoked from a notification.

Constant Value: 64 (0x00000040)

SHOW_SOURCE_PUSH_TO_TALK

public static final int SHOW_SOURCE_PUSH_TO_TALK

Flag for use with onShow(Bundle, int): indicates that the voice interaction service was invoked from a physical button.

Constant Value: 32 (0x00000020)

SHOW_WITH_ASSIST

public static final int SHOW_WITH_ASSIST

Flag received in onShow(Bundle, int): originator requested that the session be started with assist data from the currently focused activity.

Constant Value: 1 (0x00000001)

SHOW_WITH_SCREENSHOT

public static final int SHOW_WITH_SCREENSHOT

Flag received in onShow(Bundle, int): originator requested that the session be started with a screen shot of the currently focused activity.

Constant Value: 2 (0x00000002)

VoiceInteractionSession

public VoiceInteractionSession (Context context)

VoiceInteractionSession

public VoiceInteractionSession (Context context, 
                Handler handler)

closeSystemDialogs

public void closeSystemDialogs ()

Request that all system dialogs (and status bar shade etc) be closed, allowing access to the session's UI. This will not cause the lock screen to be dismissed.

dump

public void dump (String prefix, 
                FileDescriptor fd, 
                PrintWriter writer, 
                String[] args)

Print the Service's state into the given stream. This gets invoked by VoiceInteractionSessionService when its Service Service.dump(FileDescriptor, PrintWriter, String) method is called.

finish

public void finish ()

Finish the session. This completely destroys the session -- the next time it is shown, an entirely new one will be created. You do not normally call this function; instead, use hide() and allow the system to destroy your session if it needs its RAM.

getContext

public Context getContext ()

getDisabledShowContext

public int getDisabledShowContext ()

Equivalent to VoiceInteractionService.getDisabledShowContext.

getLayoutInflater

public LayoutInflater getLayoutInflater ()

Convenience for inflating views.

getUserDisabledShowContext

public int getUserDisabledShowContext ()

Return which show context flags have been disabled by the user through the system settings UI, so the session will never get this data. Returned flags are any combination of VoiceInteractionSession.SHOW_WITH_ASSIST and VoiceInteractionSession.SHOW_WITH_SCREENSHOT. Note that this only tells you about global user settings, not about restrictions that may be applied contextual based on the current application the user is in or other transient states.

getWindow

public Dialog getWindow ()

Retrieve the window being used to show the session's UI.

hide

public void hide ()

Hide the session's UI, if currently shown. Call this when you are done with your user interaction.

onAssistStructureFailure

public void onAssistStructureFailure (Throwable failure)

Called when there has been a failure transferring the AssistStructure to the assistant. This may happen, for example, if the data is too large and results in an out of memory exception, the data has been cleared during transferring due to the new incoming assist data, or the client has provided corrupt data. This will be called immediately before onHandleAssist(Bundle, AssistStructure, AssistContent) and the AssistStructure supplied there afterwards will be null.

onBackPressed

public void onBackPressed ()

Called when the user presses the back button while focus is in the session UI. Note that this will only happen if the session UI has requested input focus in its window; otherwise, the back key will go to whatever window has focus and do whatever behavior it normally has there. The default implementation simply calls hide().

onCancelRequest

public void onCancelRequest (VoiceInteractionSession.Request request)

Called when the VoiceInteractor has asked to cancel a Request that was previously delivered to onRequestConfirmation(ConfirmationRequest), onRequestPickOption(PickOptionRequest), onRequestCompleteVoice(CompleteVoiceRequest), onRequestAbortVoice(AbortVoiceRequest), or onRequestCommand(CommandRequest).

onCloseSystemDialogs

public void onCloseSystemDialogs ()

Sessions automatically watch for requests that all system UI be closed (such as when the user presses HOME), which will appear here. The default implementation always calls hide().

onComputeInsets

public void onComputeInsets (VoiceInteractionSession.Insets outInsets)

Compute the interesting insets into your UI. The default implementation sets outInsets.contentInsets.top to the height of the window, meaning it should not adjust content underneath. The default touchable insets are Insets#TOUCHABLE_INSETS_FRAME, meaning it consumes all touch events within its window frame.

onConfigurationChanged

public void onConfigurationChanged (Configuration newConfig)

Called by the system when the device configuration changes while your component is running. Note that, unlike activities, other components are never restarted when a configuration changes: they must always deal with the results of the change, such as by re-retrieving resources.

At the time that this function has been called, your Resources object will have been updated to return resource values matching the new configuration.

For more information, read Handling Runtime Changes.

onCreate

public void onCreate ()

Initiatize a new session. At this point you don't know exactly what this session will be used for; you will find that out in onShow(Bundle, int).

onCreateContentView

public View onCreateContentView ()

Hook in which to create the session's UI.

onDestroy

public void onDestroy ()

Last callback to the session as it is being finished.

onDirectActionsInvalidated

public void onDirectActionsInvalidated (VoiceInteractionSession.ActivityId activityId)

Called when the direct actions are invalidated.

onGetSupportedCommands

public boolean[] onGetSupportedCommands (String[] commands)

Request to query for what extended commands the session supports.

onHandleAssist

public void onHandleAssist (Bundle data, 
                AssistStructure structure, 
                AssistContent content)

This method was deprecated in API level 29.
use onHandleAssist(android.service.voice.VoiceInteractionSession.AssistState)

Called to receive data from the application that the user was currently viewing when - * an assist session is started. If the original show request did not specify SHOW_WITH_ASSIST, this method will not be called.

onHandleAssist

public void onHandleAssist (VoiceInteractionSession.AssistState state)

Called to receive data from the application that the user was currently viewing when an assist session is started. If the original show request did not specify SHOW_WITH_ASSIST, AssistState parameter will only provide ActivityId. If there was a failure to write the assist data to AssistStructure, the AssistState#getAssistStructure() will return null.

This method is called for all activities along with an index and count that indicates which activity the data is for. index will be between 0 and count-1 and this method is called once for each activity in no particular order. The count indicates how many activities to expect assist data for, including the top focused one. The focused activity can be determined by calling AssistState#isFocused().

To be responsive to assist requests, process assist data as soon as it is received, without waiting for all queued activities to return assist data.

onHandleAssistSecondary

public void onHandleAssistSecondary (Bundle data, 
                AssistStructure structure, 
                AssistContent content, 
                int index, 
                int count)

This method was deprecated in API level 29.
use onHandleAssist(android.service.voice.VoiceInteractionSession.AssistState)

Called to receive data from other applications that the user was or is interacting with, that are currently on the screen in a multi-window display environment, not including the currently focused activity. This could be a free-form window, a picture-in-picture window, or another window in a split-screen display.

This method is very similar to onHandleAssist(Bundle, AssistStructure, AssistContent) except that it is called for additional non-focused activities along with an index and count that indicates which additional activity the data is for. index will be between 1 and count-1 and this method is called once for each additional window, in no particular order. The count indicates how many windows to expect assist data for, including the top focused activity, which continues to be returned via onHandleAssist(Bundle, AssistStructure, AssistContent).

To be responsive to assist requests, process assist data as soon as it is received, without waiting for all queued activities to return assist data.

onHandleScreenshot

public void onHandleScreenshot (Bitmap screenshot)

Called to receive a screenshot of what the user was currently viewing when an assist session is started. May be null if screenshots are disabled by the user, policy, or application. If the original show request did not specify SHOW_WITH_SCREENSHOT, this method will not be called.

onHide

public void onHide ()

Called immediately after stopping to show the session UI.

onKeyDown

public boolean onKeyDown (int keyCode, 
                KeyEvent event)

Called when a key down event has occurred. If you return true, you can first call KeyEvent.startTracking() to have the framework track the event through its onKeyUp(int, android.view.KeyEvent) and also call your onKeyLongPress(int, android.view.KeyEvent) if it occurs.

onKeyLongPress

public boolean onKeyLongPress (int keyCode, 
                KeyEvent event)

Called when a long press has occurred. If you return true, the final key up will have KeyEvent#FLAG_CANCELED and KeyEvent#FLAG_CANCELED_LONG_PRESS set. Note that in order to receive this callback, someone in the event change must return true from onKeyDown(int, KeyEvent) and call KeyEvent#startTracking() on the event.

onKeyMultiple

public boolean onKeyMultiple (int keyCode, 
                int count, 
                KeyEvent event)

Called when a user's interaction with an analog control, such as flinging a trackball, generates simulated down/up events for the same key multiple times in quick succession.

onKeyUp

public boolean onKeyUp (int keyCode, 
                KeyEvent event)

Called when a key up event has occurred.

onLockscreenShown

public void onLockscreenShown ()

Called when the lockscreen was shown.

onLowMemory

public void onLowMemory ()

This is called when the overall system is running low on memory, and actively running processes should trim their memory usage. While the exact point at which this will be called is not defined, generally it will happen when all background process have been killed. That is, before reaching the point of killing processes hosting service and foreground UI that we would like to avoid killing.

onPrepareShow

public void onPrepareShow (Bundle args, 
                int showFlags)

Called prior to onShow(Bundle, int) before any UI setup has occurred. Not generally useful.

onRequestAbortVoice

public void onRequestAbortVoice (VoiceInteractionSession.AbortVoiceRequest request)

Request to abort the voice interaction session because the voice activity can not complete its interaction using voice. Corresponds to VoiceInteractor.AbortVoiceRequest. The default implementation just sends an empty confirmation back to allow the activity to exit.

onRequestCommand

public void onRequestCommand (VoiceInteractionSession.CommandRequest request)

Process an arbitrary extended command from the caller, corresponding to a VoiceInteractor.CommandRequest.

onRequestCompleteVoice

public void onRequestCompleteVoice (VoiceInteractionSession.CompleteVoiceRequest request)

Request to complete the voice interaction session because the voice activity successfully completed its interaction using voice. Corresponds to VoiceInteractor.CompleteVoiceRequest. The default implementation just sends an empty confirmation back to allow the activity to exit.

onRequestConfirmation

public void onRequestConfirmation (VoiceInteractionSession.ConfirmationRequest request)

Request to confirm with the user before proceeding with an unrecoverable operation, corresponding to a VoiceInteractor.ConfirmationRequest.

onRequestPickOption

public void onRequestPickOption (VoiceInteractionSession.PickOptionRequest request)

Request for the user to pick one of N options, corresponding to a VoiceInteractor.PickOptionRequest.

onShow

public void onShow (Bundle args, 
                int showFlags)

Called when the session UI is going to be shown. This is called after onCreateContentView() (if the session's content UI needed to be created) and immediately prior to the window being shown. This may be called while the window is already shown, if a show request has come in while it is shown, to allow you to update the UI to match the new show arguments.

onTaskFinished

public void onTaskFinished (Intent intent, 
                int taskId)

Called when the last activity of a task initiated by startVoiceActivity(android.content.Intent) has finished. The default implementation calls finish() on the assumption that this represents the completion of a voice action. You can override the implementation if you would like a different behavior.

onTaskStarted

public void onTaskStarted (Intent intent, 
                int taskId)

Called when a task initiated by startVoiceActivity(android.content.Intent) has actually started.

onTrimMemory

public void onTrimMemory (int level)

Called when the operating system has determined that it is a good time for a process to trim unneeded memory from its process. You should never compare to exact values of the level, since new intermediate values may be added -- you will typically want to compare if the value is greater or equal to a level you are interested in.

To retrieve the processes current trim level at any point, you can use ActivityManager.getMyMemoryState(RunningAppProcessInfo).

performDirectAction

public final void performDirectAction (DirectAction action, 
                Bundle extras, 
                CancellationSignal cancellationSignal, 
                Executor resultExecutor, 
                Consumer<Bundle> resultListener)

Asks that an action be performed by the app. This will send a request to the app which provided this action.

An action could take time to execute and the result is provided asynchronously via a callback. If the action is taking longer and you want to cancel its execution you can pass in a cancellation signal through which to notify the app to abort the action.

registerVisibleActivityCallback

public final void registerVisibleActivityCallback (Executor executor, 
                VoiceInteractionSession.VisibleActivityCallback callback)

Registers a callback that will be notified when visible activities have been changed. Note: The VisibleActivityCallback#onVisible(VisibleActivityInfo) will be called immediately with current visible activities when the callback is registered for the first time. If the callback is already registered, this method does nothing.

requestDirectActions

public final void requestDirectActions (VoiceInteractionSession.ActivityId activityId, 
                CancellationSignal cancellationSignal, 
                Executor resultExecutor, 
                Consumer<List<DirectAction>> callback)

Requests a list of supported actions from an app.

setContentView

public void setContentView (View view)

setDisabledShowContext

public void setDisabledShowContext (int flags)

Equivalent to VoiceInteractionService.setDisabledShowContext(int).

setKeepAwake

public void setKeepAwake (boolean keepAwake)

Set whether this session will keep the device awake while it is running a voice activity. By default, the system holds a wake lock for it while in this state, so that it can work even if the screen is off. Setting this to false removes that wake lock, allowing the CPU to go to sleep. This is typically used if the session decides it has been waiting too long for a response from the user and doesn't want to let this continue to drain the battery.

Passing false here will release the wake lock, and you can call later with true to re-acquire it. It will also be automatically re-acquired for you each time you start a new voice activity task -- that is when you call startVoiceActivity(Intent).

setTheme

public void setTheme (int theme)

You can call this to customize the theme used by your IME's window. This must be set before onCreate(), so you will typically call it in your constructor with the resource ID of your custom theme.

setUiEnabled

public void setUiEnabled (boolean enabled)

Control whether the UI layer for this session is enabled. It is enabled by default. If set to false, you will not be able to provide a UI through onCreateContentView().

show

public void show (Bundle args, 
                int flags)

Show the UI for this session. This asks the system to go through the process of showing your UI, which will eventually culminate in onShow(Bundle, int). This is similar to calling VoiceInteractionService.showSession.

startAssistantActivity

public void startAssistantActivity (Intent intent, 
                Bundle bundle)

Ask that a new assistant activity be started. This will create a new task in the in activity manager: this means that Intent.FLAG_ACTIVITY_NEW_TASK will be set for you to make it a new task.

The newly started activity will be displayed on top of other activities in the system in a new layer that is not affected by multi-window mode. Tasks started from this activity will go into the normal activity layer and not this new layer.

By default, the system will create a window for the UI for this session. If you are using an assistant activity instead, then you can disable the window creation by calling setUiEnabled(boolean) in onPrepareShow(android.os.Bundle, int).

startAssistantActivity

public void startAssistantActivity (Intent intent)

Ask that a new assistant activity be started. This will create a new task in the in activity manager: this means that Intent.FLAG_ACTIVITY_NEW_TASK will be set for you to make it a new task.

The newly started activity will be displayed on top of other activities in the system in a new layer that is not affected by multi-window mode. Tasks started from this activity will go into the normal activity layer and not this new layer.

By default, the system will create a window for the UI for this session. If you are using an assistant activity instead, then you can disable the window creation by calling setUiEnabled(boolean) in onPrepareShow(android.os.Bundle, int).

startVoiceActivity

public void startVoiceActivity (Intent intent)

Ask that a new activity be started for voice interaction. This will create a new dedicated task in the activity manager for this voice interaction session; this means that Intent.FLAG_ACTIVITY_NEW_TASK will be set for you to make it a new task.

The newly started activity will be displayed to the user in a special way, as a layer under the voice interaction UI.

As the voice activity runs, it can retrieve a VoiceInteractor through which it can perform voice interactions through your session. These requests for voice interactions will appear as callbacks on onGetSupportedCommands(String), onRequestConfirmation(ConfirmationRequest), onRequestPickOption(PickOptionRequest), onRequestCompleteVoice(CompleteVoiceRequest), onRequestAbortVoice(AbortVoiceRequest), or onRequestCommand(CommandRequest)

You will receive a call to onTaskStarted(Intent, int) when the task starts up and onTaskFinished(Intent, int) when the last activity has finished.

unregisterVisibleActivityCallback

public final void unregisterVisibleActivityCallback (VoiceInteractionSession.VisibleActivityCallback callback)

Unregisters the callback.