PersonalContextManager

public final class PersonalContextManager
extends Object

java.lang.Object
   ↳ android.app.personalcontext.PersonalContextManager

Client facing access to the PersonalContext service.

The PersonalContext service is a framework for securely gathering device context (such as screen context and device state changes) and delivering it to a set of system configured components to combine and infer personalized information and actions. The personalized contextual information used by the PersonalContext service is implementation specific to the participating component. The resulting output is shown in contextually relevant environment, such as notification replies or auto-fill suggestions.

The service accepts a flow of contextual details from activity on the device, such as notifications and screen content. This data is used by a set of components to determine relevant information and suggestions for the user. The incoming data takes the form of various ContextHint subclasses, each tailored to a particular captured data type. Entities both inside and outside the PersonalContext service through ERROR(publishTriggeringHint(List,List)/#publishTriggeringHint(java.util.List,java.util.List) publishTriggeringHint(List,List)) and its variants.

Often times, the publisher might know that the results should be delivered to a particular surface to render. For example, NotificationHint can lead to actions or suggestions within the notification shade. In these cases, the surface can be targeted by the publisher to receiving the results by specifying the ERROR(RenderToken/android.app.personalcontext.RenderToken RenderToken) associated with the surface's renderer.

Core PersonalContext entities and roles:

Summary

Nested classes

interface PersonalContextManager.OnPersonalContextModeChangedListener

Callback interface to receive updates when personal context mode for an application changes. 

Constants

String ACTION_LAUNCH_PERSONAL_CONTEXT_UNDERSTANDER_CONSENT_INTRO

Activity Action: Start an activity that prompts the user with understander-specific consent information.

String ACTION_PERSONAL_CONTEXT_ENABLED_CHANGED

Intent that is broadcast when the state of isEnabled() changes.

int DESTINATION_AUGMENTED_AUTOFILL

Destination for augmented autofill responses that show inline in the IME's suggestion bar.

int DESTINATION_EMBEDDED

Destination for an embedded visualization.

int DESTINATION_NOTIFICATION

Destination for suggestion chips in notifications.

int DESTINATION_REMOTE_AUTOFILL

Destination for screen whispers in the status bar that fill in text in an app's text input on activation.

int DESTINATION_SCREEN_WHISPER

Destination for screen whispers in the status bar.

int DESTINATION_UNIVERSAL

Destination for a general-purpose surface for displaying insights that is provided by the device manufacturer.

int DESTINATION_UNKNOWN

Unknown destination type.

String EXTRA_FEEDBACK_REQUEST

Intent Extra: The name of the extra storing the FeedbackRequest in the bundle that the understander's feedback activity is started with.

String EXTRA_PROMPT_REQUEST

Intent Extra: The PromptRequest associated with a prompt.

String PERSONAL_CONTEXT_SERVICE

The name of the Personal Context service.

int UNDERSTANDER_TYPE_AGENT

Understander type for a personal context understander that is provided by the user-selected digital assistant on the device, implementing ERROR(/android.app.personalcontext.understander.ContextUnderstanderService).

int UNDERSTANDER_TYPE_OEM

Understander type for a personal context understander that is provided by the device manufacturer, implementing ERROR(/android.app.personalcontext.understander.ContextUnderstanderService).

int UNDERSTANDER_TYPE_UNKNOWN

Unknown understander type.

Public methods

List<ComponentName> getEnabledUnderstanders()

Returns the list of enabled personal context understanders.

boolean isEnabled()

Returns whether the Personal Context service is enabled system-wide.

boolean isPersonalContextModeEnabled(String packageName)

Returns true if personal context data collection is enabled for the given package.

boolean isPersonalContextModeEnabled()

Returns true if personal context data collection is enabled for the calling package.

void registerOnPersonalContextEnabledChangedListener(Executor executor, Runnable listener)

Registers a listener to be notified when the overall personal context service enabled state changes.

void registerOnPersonalContextModeChangedListener(String packageName, Executor executor, PersonalContextManager.OnPersonalContextModeChangedListener listener)

Registers a listener to be notified when the personal context mode setting for a specific package changes.

void registerOnPersonalContextModeChangedListener(Executor executor, PersonalContextManager.OnPersonalContextModeChangedListener listener)

Registers a listener to be notified when the personal context mode setting for the calling application changes.

void registerUnderstanderCallback(Executor executor, Runnable callback)

Registers a callback to be notified when the list of enabled personal context understanders changes.

void respondToPrompt(PromptResponse promptResponse)

Responds to a prompt with the chosen insight.

void respondToUnderstanderRegistrationRequest(RegistrationResponse response)

Responds to an understander registration request.

void unregisterOnPersonalContextEnabledChangedListener(Runnable listener)

Unregisters a listener previously registered with registerOnPersonalContextEnabledChangedListener(Executor, Runnable).

void unregisterOnPersonalContextModeChangedListener(PersonalContextManager.OnPersonalContextModeChangedListener listener)

Unregisters a listener previously registered with registerOnPersonalContextModeChangedListener(String, Executor, OnPersonalContextModeChangedListener).

void unregisterUnderstanderCallback(Runnable callback)

Unregisters a previously registered callback.

Inherited methods

Constants

Added in version 37.2 
public static final String ACTION_LAUNCH_PERSONAL_CONTEXT_UNDERSTANDER_CONSENT_INTRO

Activity Action: Start an activity that prompts the user with understander-specific consent information.

This action is handled by an activity in the package of the understander component. If no activity is specified, this consent introduction is skipped and the user is directly prompted with system consent dialog for the understander.

The result of this activity should be passed back through the ResultReceiver stored in ERROR(/#EXTRA_PERSONAL_CONTEXT_UNDERSTANDER_CONSENT_INTRO_RESULT_RECEIVER) extra.

Constant Value: "android.app.personalcontext.action.LAUNCH_PERSONAL_CONTEXT_UNDERSTANDER_CONSENT_INTRO"

ACTION_PERSONAL_CONTEXT_ENABLED_CHANGED

Added in version 37.2 
public static final String ACTION_PERSONAL_CONTEXT_ENABLED_CHANGED

Intent that is broadcast when the state of isEnabled() changes. This broadcast is only sent to registered receivers.

Constant Value: "android.app.personalcontext.action.PERSONAL_CONTEXT_ENABLED_CHANGED"

DESTINATION_AUGMENTED_AUTOFILL

Added in version 37.2 
public static final int DESTINATION_AUGMENTED_AUTOFILL

Destination for augmented autofill responses that show inline in the IME's suggestion bar. This destination only accepts a AugmentedAutofillInsight.

Constant Value: 16 (0x00000010)

DESTINATION_EMBEDDED

Added in version 37.2 
public static final int DESTINATION_EMBEDDED

Destination for an embedded visualization.

The presence of this destination indicates that the hint was sent in by a client app requesting a visualization. The understander should set an InsightVisualizerSession via UnderstandResult.Builder.setVisualizerSession(InsightVisualizerSession) to indicate that it wants to generate a visualization for the client. The initial hint, and all additional hints from the client for this session, will be provided directly to InsightVisualizerSession.createRemoteViewsForHints. If an InsightVisualizerSession is not provided for this destination, the visualization session will be closed.

No insight should be provided for this destination, it will be ignored.

This destination will only be provided to agent understanders registered with ERROR(UnderstanderType.UNDERSTANDER_TYPE_AGENT/android.app.personalcontext.PersonalContextManager.UnderstanderType#UNDERSTANDER_TYPE_AGENT UnderstanderType.UNDERSTANDER_TYPE_AGENT).

Constant Value: 32 (0x00000020)

DESTINATION_NOTIFICATION

Added in version 37.2 
public static final int DESTINATION_NOTIFICATION

Destination for suggestion chips in notifications. This destination only accepts a NotificationInsight.

Constant Value: 2 (0x00000002)

DESTINATION_REMOTE_AUTOFILL

Added in version 37.2 
public static final int DESTINATION_REMOTE_AUTOFILL

Destination for screen whispers in the status bar that fill in text in an app's text input on activation. This destination only accepts a ScreenWhisperAutofillInsight.

Constant Value: 8 (0x00000008)

DESTINATION_SCREEN_WHISPER

Added in version 37.2 
public static final int DESTINATION_SCREEN_WHISPER

Destination for screen whispers in the status bar. This destination only accepts a ScreenWhisperInsight.

Constant Value: 4 (0x00000004)

DESTINATION_UNIVERSAL

Added in version 37.2 
public static final int DESTINATION_UNIVERSAL

Destination for a general-purpose surface for displaying insights that is provided by the device manufacturer.

This destination will only be provided to OEM understanders registered with ERROR(UnderstanderType.UNDERSTANDER_TYPE_OEM/android.app.personalcontext.PersonalContextManager.UnderstanderType#UNDERSTANDER_TYPE_OEM UnderstanderType.UNDERSTANDER_TYPE_OEM).

Constant Value: 1 (0x00000001)

DESTINATION_UNKNOWN

Added in version 37.2 
public static final int DESTINATION_UNKNOWN

Unknown destination type. The framework will never deliberately send this type. No response is expected, and any response will be ignored.

Constant Value: 0 (0x00000000)

EXTRA_FEEDBACK_REQUEST

Added in version 37.2 
public static final String EXTRA_FEEDBACK_REQUEST

Intent Extra: The name of the extra storing the FeedbackRequest in the bundle that the understander's feedback activity is started with.

Constant Value: "android.app.personalcontext.extra.FEEDBACK_REQUEST"

EXTRA_PROMPT_REQUEST

Added in version 37.2 
public static final String EXTRA_PROMPT_REQUEST

Intent Extra: The PromptRequest associated with a prompt.

This is a PromptRequest extra.

Constant Value: "android.app.personalcontext.extra.PROMPT_REQUEST"

PERSONAL_CONTEXT_SERVICE

Added in version 37.2 
public static final String PERSONAL_CONTEXT_SERVICE

The name of the Personal Context service.

Constant Value: "personal_context"

UNDERSTANDER_TYPE_AGENT

Added in version 37.2 
public static final int UNDERSTANDER_TYPE_AGENT

Understander type for a personal context understander that is provided by the user-selected digital assistant on the device, implementing ERROR(/android.app.personalcontext.understander.ContextUnderstanderService).

The user must consent before the understander can participate in the personal context flow.

Constant Value: 1 (0x00000001)

UNDERSTANDER_TYPE_OEM

Added in version 37.2 
public static final int UNDERSTANDER_TYPE_OEM

Understander type for a personal context understander that is provided by the device manufacturer, implementing ERROR(/android.app.personalcontext.understander.ContextUnderstanderService).

Like UNDERSTANDER_TYPE_AGENT, the user must consent before the understander can participate in the personal context flow.

Data egress will be more limited for an OEM understander. For instance, UnderstandRequest.getSessionId() will return null.

Constant Value: 2 (0x00000002)

UNDERSTANDER_TYPE_UNKNOWN

Added in version 37.2 
public static final int UNDERSTANDER_TYPE_UNKNOWN

Unknown understander type.

Constant Value: 0 (0x00000000)

Public methods

getEnabledUnderstanders

Added in version 37.2 
public List<ComponentName> getEnabledUnderstanders ()

Returns the list of enabled personal context understanders.

Returns
List<ComponentName> The list of currently enabled understanders.
This value cannot be null.

isEnabled

Added in version 37.2 
public boolean isEnabled ()

Returns whether the Personal Context service is enabled system-wide.

Returns
boolean

isPersonalContextModeEnabled

Added in version 37.2 
public boolean isPersonalContextModeEnabled (String packageName)

Returns true if personal context data collection is enabled for the given package.

When disabled, this setting stops all data collection sources of personal context for a particular application, such as from the Content Capture API and notifications content. As a result, contextual information from this application will not participate in the data capture and processing within the PersonalContext service, excluding this information from being seen by participating components and thus restricting any PersonalContext experience from including this application.

Querying information about a package other than the caller's package requires Manifest.permission.QUERY_ALL_PACKAGES.

Parameters
packageName String: package name of the application to read the setting for.
This value cannot be null.
Returns
boolean

isPersonalContextModeEnabled

Added in version 37.2 
public boolean isPersonalContextModeEnabled ()

Returns true if personal context data collection is enabled for the calling package.

When disabled, this setting stops all data collection sources of personal context for a particular application, such as from the Content Capture API and notifications content. As a result, contextual information from this application will not participate in the data capture and processing within the PersonalContext service, excluding this information from being seen by participating components and thus restricting any PersonalContext experience from including this application.

Returns
boolean

registerOnPersonalContextEnabledChangedListener

Added in version 37.2 
public void registerOnPersonalContextEnabledChangedListener (Executor executor, 
                Runnable listener)

Registers a listener to be notified when the overall personal context service enabled state changes.

Parameters
executor Executor: the executor on which the listener will be called.
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.
listener Runnable: the listener to register.
This value cannot be null.

registerOnPersonalContextModeChangedListener

Added in version 37.2 
public void registerOnPersonalContextModeChangedListener (String packageName, 
                Executor executor, 
                PersonalContextManager.OnPersonalContextModeChangedListener listener)

Registers a listener to be notified when the personal context mode setting for a specific package changes.

Querying information about a package other than the caller's package requires package visibility (e.g. via QUERY_ALL_PACKAGES or <queries> in the manifest).

Parameters
packageName String: package name of the application to listen for setting changes.
This value cannot be null.
executor Executor: the executor on which the listener will be called.
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.
listener PersonalContextManager.OnPersonalContextModeChangedListener: the listener to register.
This value cannot be null.
Throws
SecurityException if the caller cannot query the personal context mode for the specified package

registerOnPersonalContextModeChangedListener

Added in version 37.2 
public void registerOnPersonalContextModeChangedListener (Executor executor, 
                PersonalContextManager.OnPersonalContextModeChangedListener listener)

Registers a listener to be notified when the personal context mode setting for the calling application changes.

Parameters
executor Executor: the executor on which the listener will be called.
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.
listener PersonalContextManager.OnPersonalContextModeChangedListener: the listener to register.
This value cannot be null.

registerUnderstanderCallback

Added in version 37.2 
public void registerUnderstanderCallback (Executor executor, 
                Runnable callback)

Registers a callback to be notified when the list of enabled personal context understanders changes.

This callback registration does not require any permissions. When notified of a change, clients can poll the relevant settings (e.g. calling getEnabledUnderstanders()) to obtain updated state.

Parameters
executor Executor: The executor on which to run 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 Runnable: The callback to register.
This value cannot be null.

respondToPrompt

Added in version 37.2 
public void respondToPrompt (PromptResponse promptResponse)

Responds to a prompt with the chosen insight.

Parameters
promptResponse PromptResponse: the response containing the chosen insight.
This value cannot be null.

respondToUnderstanderRegistrationRequest

Added in version 37.2 
public void respondToUnderstanderRegistrationRequest (RegistrationResponse response)

Responds to an understander registration request.

Parameters
response RegistrationResponse: The response to return.
This value cannot be null.

unregisterOnPersonalContextEnabledChangedListener

Added in version 37.2 
public void unregisterOnPersonalContextEnabledChangedListener (Runnable listener)

Unregisters a listener previously registered with registerOnPersonalContextEnabledChangedListener(Executor, Runnable).

Parameters
listener Runnable: the listener to unregister.
This value cannot be null.

unregisterOnPersonalContextModeChangedListener

Added in version 37.2 
public void unregisterOnPersonalContextModeChangedListener (PersonalContextManager.OnPersonalContextModeChangedListener listener)

Unregisters a listener previously registered with registerOnPersonalContextModeChangedListener(String, Executor, OnPersonalContextModeChangedListener).

Parameters
listener PersonalContextManager.OnPersonalContextModeChangedListener: the listener to unregister.
This value cannot be null.

unregisterUnderstanderCallback

Added in version 37.2 
public void unregisterUnderstanderCallback (Runnable callback)

Unregisters a previously registered callback.

Parameters
callback Runnable: The callback to unregister.
This value cannot be null.