VoiceInteractionSession

public class VoiceInteractionSession
extends Object implements KeyEvent.Callback, ComponentCallbacks2

java.lang.Object
   ↳ android.service.voice.VoiceInteractionSession


An active voice interaction session, providing a facility for the implementation to interact with the user in the voice interaction layer. The user interface is initially shown by default, and can be created by overriding onCreateContentView() in which the UI can be built.

A voice interaction session can be self-contained, ultimately calling finish() when done. It can also initiate voice interactions with applications by calling startVoiceActivity(Intent)

.

Summary

Nested classes

class VoiceInteractionSession.AbortVoiceRequest

A request to report that the current user interaction can not be completed with voice, as per VoiceInteractor.AbortVoiceRequest

class VoiceInteractionSession.ActivityId

Represents the id of an assist source activity. 

class VoiceInteractionSession.AssistState

Represents assist state captured when this session was started. 

class VoiceInteractionSession.CommandRequest

A generic vendor-specific request, as per VoiceInteractor.CommandRequest

class VoiceInteractionSession.CompleteVoiceRequest

A request to simply inform the user that the voice operation has completed, as per VoiceInteractor.CompleteVoiceRequest

class VoiceInteractionSession.ConfirmationRequest

A request for confirmation from the user of an operation, as per VoiceInteractor.ConfirmationRequest

class VoiceInteractionSession.Insets

Information about where interesting parts of the input method UI appear. 

class VoiceInteractionSession.PickOptionRequest

A request for the user to pick from a set of option, as per VoiceInteractor.PickOptionRequest

class VoiceInteractionSession.Request

Base class representing a request from a voice-driver app to perform a particular voice operation with the user. 

interface VoiceInteractionSession.VisibleActivityCallback

Callback interface for receiving visible activity changes used for assistant usage. 

Constants

String KEY_SHOW_SESSION_ID

Bundle key used to specify the id when the system prepares to show session.

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).

int SHOW_SOURCE_APPLICATION

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

int SHOW_SOURCE_ASSIST_GESTURE

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

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.

int SHOW_SOURCE_NOTIFICATION

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

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.

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.

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.

Inherited constants

Public constructors

VoiceInteractionSession(Context context)
VoiceInteractionSession(Context context, Handler handler)

Public methods

void closeSystemDialogs()

Request that all system dialogs (and status bar shade etc) be closed, allowing access to the session's UI.

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

Print the Service's state into the given stream.

void finish()

Finish the session.

Context getContext()
int getDisabledShowContext()

Equivalent to VoiceInteractionService.getDisabledShowContext.

LayoutInflater getLayoutInflater()

Convenience for inflating views.

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.

Dialog getWindow()

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

void hide()

Hide the session's UI, if currently shown.

void onAssistStructureFailure(Throwable failure)

Called when there has been a failure transferring the AssistStructure to the assistant.

void onBackPressed()

Called when the user presses the back button while focus is in the session UI.

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).

void onCloseSystemDialogs()

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

void onComputeInsets(VoiceInteractionSession.Insets outInsets)

Compute the interesting insets into your UI.

void onConfigurationChanged(Configuration newConfig)

Called by the system when the device configuration changes while your component is running.

void onCreate()

Initiatize a new session.

View onCreateContentView()

Hook in which to create the session's UI.

void onDestroy()

Last callback to the session as it is being finished.

void onDirectActionsInvalidated(VoiceInteractionSession.ActivityId activityId)

Called when the direct actions are invalidated.

boolean[] onGetSupportedCommands(String[] commands)

Request to query for what extended commands the session supports.

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

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

void onHandleAssist(VoiceInteractionSession.AssistState state)

Called to receive data from the application that the user was currently viewing when an assist session is started.

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)

void onHandleScreenshot(Bitmap screenshot)

Called to receive a screenshot of what the user was currently viewing when an assist session is started.

void onHide()

Called immediately after stopping to show the session UI.

boolean onKeyDown(int keyCode, KeyEvent event)

Called when a key down event has occurred.

boolean onKeyLongPress(int keyCode, KeyEvent event)

Called when a long press has occurred.

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.

boolean onKeyUp(int keyCode, KeyEvent event)

Called when a key up event has occurred.

void onLockscreenShown()

Called when the lockscreen was shown.

void onLowMemory()

This is called when the overall system is running low on memory, and actively running processes should trim their memory usage.

void onPrepareShow(Bundle args, int showFlags)

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

void onRequestAbortVoice(VoiceInteractionSession.AbortVoiceRequest request)

Request to abort the voice interaction session because the voice activity can not complete its interaction using voice.

void onRequestCommand(VoiceInteractionSession.CommandRequest request)

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

void onRequestCompleteVoice(VoiceInteractionSession.CompleteVoiceRequest request)

Request to complete the voice interaction session because the voice activity successfully completed its interaction using voice.

void onRequestConfirmation(VoiceInteractionSession.ConfirmationRequest request)

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

void onRequestPickOption(VoiceInteractionSession.PickOptionRequest request)

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

void onShow(Bundle args, int showFlags)

Called when the session UI is going to be shown.

void onTaskFinished(Intent intent, int taskId)

Called when the last activity of a task initiated by startVoiceActivity(android.content.Intent) has finished.

void onTaskStarted(Intent intent, int taskId)

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

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.

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

Asks that an action be performed by the app.

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

Registers a callback that will be notified when visible activities have been changed.

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

Requests a list of supported actions from an app.

void setContentView(View view)
void setDisabledShowContext(int flags)

Equivalent to VoiceInteractionService.setDisabledShowContext(int).

void setKeepAwake(boolean keepAwake)

Set whether this session will keep the device awake while it is running a voice activity.

void setTheme(int theme)

You can call this to customize the theme used by your IME's window.

void setUiEnabled(boolean enabled)

Control whether the UI layer for this session is enabled.

void show(Bundle args, int flags)

Show the UI for this session.

void startAssistantActivity(Intent intent, Bundle bundle)

Ask that a new assistant activity be started.

void startAssistantActivity(Intent intent)

Ask that a new assistant activity be started.

void startVoiceActivity(Intent intent)

Ask that a new activity be started for voice interaction.

final void unregisterVisibleActivityCallback(VoiceInteractionSession.VisibleActivityCallback callback)

Unregisters the callback.

Inherited methods

Constants

KEY_SHOW_SESSION_ID

Added in API level 34
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

Added in API level 24
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

Added in API level 23
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

Added in API level 23
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

Added in API level 29
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

Added in API level 29
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

Added in API level 29
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

Added in API level 23
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

Added in API level 23
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)

Public constructors

VoiceInteractionSession

Added in API level 21
public VoiceInteractionSession (Context context)

Parameters
context Context

VoiceInteractionSession

Added in API level 21
public VoiceInteractionSession (Context context, 
                Handler handler)

Parameters
context Context

handler Handler

Public methods

closeSystemDialogs

Added in API level 23
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

Added in API level 23
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.

Parameters
prefix String: Text to print at the front of each line.

fd FileDescriptor: The raw file descriptor that the dump is being sent to.

writer PrintWriter: The PrintWriter to which you should dump your state. This will be closed for you after you return.

args String: additional arguments to the dump request.

finish

Added in API level 21
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

Added in API level 23
public Context getContext ()

Returns
Context

getDisabledShowContext

Added in API level 23
public int getDisabledShowContext ()

Equivalent to VoiceInteractionService.getDisabledShowContext.

Returns
int

getLayoutInflater

Added in API level 23
public LayoutInflater getLayoutInflater ()

Convenience for inflating views.

Returns
LayoutInflater

getUserDisabledShowContext

Added in API level 23
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.

Returns
int

getWindow

Added in API level 23
public Dialog getWindow ()

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

Returns
Dialog

hide

Added in API level 23
public void hide ()

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

onAssistStructureFailure

Added in API level 23
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.

Parameters
failure Throwable: The failure exception that was thrown when building the AssistStructure.

onBackPressed

Added in API level 23
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

Added in API level 23
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).

Parameters
request VoiceInteractionSession.Request: The request that is being canceled.

onCloseSystemDialogs

Added in API level 21
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

Added in API level 23
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.

Parameters
outInsets VoiceInteractionSession.Insets: Fill in with the current UI insets.

onConfigurationChanged

Added in API level 23
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.

Parameters
newConfig Configuration: The new device configuration. This value cannot be null.

onCreate

Added in API level 23
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

Added in API level 23
public View onCreateContentView ()

Hook in which to create the session's UI.

Returns
View

onDestroy

Added in API level 21
public void onDestroy ()

Last callback to the session as it is being finished.

onDirectActionsInvalidated

Added in API level 29
public void onDirectActionsInvalidated (VoiceInteractionSession.ActivityId activityId)

Called when the direct actions are invalidated.

Parameters
activityId VoiceInteractionSession.ActivityId: This value cannot be null.

onGetSupportedCommands

Added in API level 23
public boolean[] onGetSupportedCommands (String[] commands)

Request to query for what extended commands the session supports.

Parameters
commands String: An array of commands that are being queried.

Returns
boolean[] Return an array of booleans indicating which of each entry in the command array is supported. A true entry in the array indicates the command is supported; false indicates it is not. The default implementation returns an array of all false entries.

onHandleAssist

Added in API level 23
Deprecated in API level 29
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.

Parameters
data Bundle: Arbitrary data supplied by the app through Activity.onProvideAssistData. May be null if assist data has been disabled by the user or device policy.

structure AssistStructure: If available, the structure definition of all windows currently displayed by the app. May be null if assist data has been disabled by the user or device policy; will be an empty stub if the application has disabled assist by marking its window as secure.

content AssistContent: Additional content data supplied by the app through Activity.onProvideAssistContent. May be null if assist data has been disabled by the user or device policy; will not be automatically filled in with data from the app if the app has marked its window as secure.

onHandleAssist

Added in API level 29
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.

Parameters
state VoiceInteractionSession.AssistState: The state object capturing the state of an activity. This value cannot be null.

onHandleAssistSecondary

Added in API level 24
Deprecated in API level 29
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.

Parameters
data Bundle: Arbitrary data supplied by the app through Activity.onProvideAssistData. May be null if assist data has been disabled by the user or device policy.

structure AssistStructure: If available, the structure definition of all windows currently displayed by the app. May be null if assist data has been disabled by the user or device policy; will be an empty stub if the application has disabled assist by marking its window as secure.

content AssistContent: Additional content data supplied by the app through Activity.onProvideAssistContent. May be null if assist data has been disabled by the user or device policy; will not be automatically filled in with data from the app if the app has marked its window as secure.

index int: the index of the additional activity that this data is for.

count int: the total number of additional activities for which the assist data is being returned, including the focused activity that is returned via onHandleAssist(Bundle, AssistStructure, AssistContent).

onHandleScreenshot

Added in API level 23
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.

Parameters
screenshot Bitmap: This value may be null.

onHide

Added in API level 23
public void onHide ()

Called immediately after stopping to show the session UI.

onKeyDown

Added in API level 21
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.

Parameters
keyCode int: The value in event.getKeyCode().

event KeyEvent: Description of the key event.

Returns
boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onKeyLongPress

Added in API level 21
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.

Parameters
keyCode int: The value in event.getKeyCode().

event KeyEvent: Description of the key event.

Returns
boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onKeyMultiple

Added in API level 21
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.

Parameters
keyCode int: The value in event.getKeyCode().

count int: Number of pairs as returned by event.getRepeatCount().

event KeyEvent: Description of the key event.

Returns
boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onKeyUp

Added in API level 21
public boolean onKeyUp (int keyCode, 
                KeyEvent event)

Called when a key up event has occurred.

Parameters
keyCode int: The value in event.getKeyCode().

event KeyEvent: Description of the key event.

Returns
boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

onLockscreenShown

Added in API level 23
public void onLockscreenShown ()

Called when the lockscreen was shown.

onLowMemory

Added in API level 23
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.

You should implement this method to release any caches or other unnecessary resources you may be holding on to. The system will perform a garbage collection for you after returning from this method.

Preferably, you should implement ComponentCallbacks2#onTrimMemory from ComponentCallbacks2 to incrementally unload your resources based on various levels of memory demands. That API is available for API level 14 and higher, so you should only use this onLowMemory() method as a fallback for older versions, which can be treated the same as ComponentCallbacks2#onTrimMemory with the ComponentCallbacks2.TRIM_MEMORY_COMPLETE level.

onPrepareShow

Added in API level 26
public void onPrepareShow (Bundle args, 
                int showFlags)

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

Parameters
args Bundle: The arguments that were supplied to VoiceInteractionService.showSession.

showFlags int: The show flags originally provided to VoiceInteractionService.showSession.

onRequestAbortVoice

Added in API level 23
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.

Parameters
request VoiceInteractionSession.AbortVoiceRequest: The active request.

onRequestCommand

Added in API level 23
public void onRequestCommand (VoiceInteractionSession.CommandRequest request)

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

Parameters
request VoiceInteractionSession.CommandRequest: The active request.

onRequestCompleteVoice

Added in API level 23
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.

Parameters
request VoiceInteractionSession.CompleteVoiceRequest: The active request.

onRequestConfirmation

Added in API level 23
public void onRequestConfirmation (VoiceInteractionSession.ConfirmationRequest request)

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

Parameters
request VoiceInteractionSession.ConfirmationRequest: The active request.

onRequestPickOption

Added in API level 23
public void onRequestPickOption (VoiceInteractionSession.PickOptionRequest request)

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

Parameters
request VoiceInteractionSession.PickOptionRequest: The active request.

onShow

Added in API level 23
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.

Parameters
args Bundle: The arguments that were supplied to VoiceInteractionService.showSession. Some example keys include : "invocation_type", "invocation_phone_state", KEY_SHOW_SESSION_ID, "invocation_time_ms", Intent.EXTRA_TIME ("android.intent.extra.TIME") indicating timing in milliseconds of the KeyEvent that triggered Assistant and Intent.EXTRA_ASSIST_INPUT_DEVICE_ID (android.intent.extra.ASSIST_INPUT_DEVICE_ID) referring to the device that sent the request. Starting from Android 14, the system will add KEY_SHOW_SESSION_ID, the Bundle is not null. But the application should handle null case before Android 14.

showFlags int: The show flags originally provided to VoiceInteractionService.showSession.

onTaskFinished

Added in API level 23
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.

Parameters
intent Intent: The original Intent supplied to startVoiceActivity(android.content.Intent).

taskId int: Unique ID of the finished task.

onTaskStarted

Added in API level 23
public void onTaskStarted (Intent intent, 
                int taskId)

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

Parameters
intent Intent: The original Intent supplied to startVoiceActivity(android.content.Intent).

taskId int: Unique ID of the now running task.

onTrimMemory

Added in API level 23
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. This will happen for example when it goes in the background and there is not enough memory to keep as many background processes running as desired. 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).

Parameters
level int: The context of the trim, giving a hint of the amount of trimming the application may like to perform. Value is ComponentCallbacks2.TRIM_MEMORY_COMPLETE, ComponentCallbacks2.TRIM_MEMORY_MODERATE, ComponentCallbacks2.TRIM_MEMORY_BACKGROUND, ComponentCallbacks2.TRIM_MEMORY_UI_HIDDEN, ComponentCallbacks2.TRIM_MEMORY_RUNNING_CRITICAL, ComponentCallbacks2.TRIM_MEMORY_RUNNING_LOW, or ComponentCallbacks2.TRIM_MEMORY_RUNNING_MODERATE

performDirectAction

Added in API level 29
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.

Parameters
action DirectAction: The action to be performed. This value cannot be null.

extras Bundle: Any optional extras sent to the app as part of the request This value may be null.

cancellationSignal CancellationSignal: A signal to cancel the operation in progress, or null if none.

resultExecutor Executor: The handler to receive the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

resultListener Consumer: The callback to receive the response. This value cannot be null.

registerVisibleActivityCallback

Added in API level 32
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.

Parameters
executor Executor: The executor which will be used to invoke the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback VoiceInteractionSession.VisibleActivityCallback: The callback to receive the response. This value cannot be null.

Throws
IllegalStateException if calling this method before onCreate().

requestDirectActions

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

Requests a list of supported actions from an app.

Parameters
activityId VoiceInteractionSession.ActivityId: Ths activity id of the app to get the actions from. This value cannot be null.

cancellationSignal CancellationSignal: A signal to cancel the operation in progress, or null if none.

resultExecutor Executor: The handler to receive the callback. This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback Consumer: The callback to receive the response. This value cannot be null.

setContentView

Added in API level 21
public void setContentView (View view)

Parameters
view View

setDisabledShowContext

Added in API level 23
public void setDisabledShowContext (int flags)

Equivalent to VoiceInteractionService.setDisabledShowContext(int).

Parameters
flags int

setKeepAwake

Added in API level 23
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).

Parameters
keepAwake boolean

setTheme

Added in API level 23
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.

Parameters
theme int

setUiEnabled

Added in API level 26
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().

Parameters
enabled boolean

show

Added in API level 23
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.

Parameters
args Bundle: Arbitrary arguments that will be propagated onShow(Bundle, int).

flags int: Indicates additional optional behavior that should be performed. May be any combination of VoiceInteractionSession.SHOW_WITH_ASSIST and VoiceInteractionSession.SHOW_WITH_SCREENSHOT to request that the system generate and deliver assist data on the current foreground app as part of showing the session UI.

startAssistantActivity

Added in API level 34
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).

Parameters
intent Intent: the intent used to start an assistant activity This value cannot be null.

bundle Bundle: Additional options for how the Activity should be started. See ActivityOptions for how to build the Bundle supplied here. This value cannot be null.

startAssistantActivity

Added in API level 26
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).

NOTE: if the app would like to override some options to start the Activity, use startAssistantActivity(android.content.Intent, android.os.Bundle) instead.

Parameters
intent Intent

startVoiceActivity

Added in API level 23
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.

Parameters
intent Intent: The Intent to start this voice interaction. The given Intent will always have Intent.CATEGORY_VOICE added to it, since this is part of a voice interaction.

unregisterVisibleActivityCallback

Added in API level 32
public final void unregisterVisibleActivityCallback (VoiceInteractionSession.VisibleActivityCallback callback)

Unregisters the callback.

Parameters
callback VoiceInteractionSession.VisibleActivityCallback: The callback to receive the response. This value cannot be null.