Added in API level 37.2

PersonalContextManager

class PersonalContextManager
kotlin.Any
   ↳ 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 #publishTriggeringHint(java.util.List,java.util.List) and its variants.

Often times, the publisher might know that the results should be delivered to a particular surface to render. For example, android.app.personalcontext.hint.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 RenderToken associated with the surface's renderer.

Core PersonalContext entities and roles:

  • ContextHint implementations are the input into the PersonalContext service. Each subclass captures domain specific information about a particular device activity, such as android.app.personalcontext.hint.CallHint.
  • @link ContextInsight represents information and actions derived from ContextHints. This information is domain agnostic, allowing for display in different environments.
  • android.app.personalcontext.refiner.HintRefinerService receive ContextHints and have the opportunity to generate ContextHints based on the input data.
  • android.app.personalcontext.understander.ContextUnderstanderService is downstream from android.app.personalcontext.refiner.HintRefinerServices receiving all generated ContextHints based on its specified android.app.personalcontext.hint.HintFilter. An understander service is not required to produce ContextInsights from the inbound ContextHints and may produce ContextInsights by calling #publishInsight(java.util.List) at any time.
  • android.app.personalcontext.renderer.InsightRendererService handle showing resulting ContextInsights. Renderers integrate with their given surfaces, such as notifications and auto-fill suggestions.
  • RenderToken allow for ContextHint publishers to specify the android.app.personalcontext.renderer.InsightRendererService that should any ContextInsight generated from the hint.

Summary

Nested classes
abstract

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

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

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

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

Destination for an embedded visualization.
static Int

Destination for suggestion chips in notifications.
static Int

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

Destination for screen whispers in the status bar.
static Int

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

Unknown destination type.
static String

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

Intent Extra: The PromptRequest associated with a prompt.
static String

The name of the Personal Context service.
static Int

Understander type for a personal context understander that is provided by the user-selected digital assistant on the device, implementing android.
static Int

Understander type for a personal context understander that is provided by the device manufacturer, implementing android.
static Int

Unknown understander type.
Public methods
MutableList<ComponentName!>

Returns the list of enabled personal context understanders.
Boolean

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

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

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

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

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

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

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

Responds to a prompt with the chosen insight.
Unit

Responds to an understander registration request.
Unit

Unregisters a listener previously registered with registerOnPersonalContextEnabledChangedListener.
Unit

Unregisters a listener previously registered with #registerOnPersonalContextModeChangedListener.
Unit

Unregisters a previously registered callback.

Constants

Added in API level 37.2
static val ACTION_LAUNCH_PERSONAL_CONTEXT_UNDERSTANDER_CONSENT_INTRO: String

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 android.os.ResultReceiver stored in #EXTRA_PERSONAL_CONTEXT_UNDERSTANDER_CONSENT_INTRO_RESULT_RECEIVER extra.

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

ACTION_PERSONAL_CONTEXT_ENABLED_CHANGED

Added in API level 37.2
static val ACTION_PERSONAL_CONTEXT_ENABLED_CHANGED: String

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

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

DESTINATION_AUGMENTED_AUTOFILL

Added in API level 37.2
static val DESTINATION_AUGMENTED_AUTOFILL: Int

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

Value: 16

DESTINATION_EMBEDDED

Added in API level 37.2
static val DESTINATION_EMBEDDED: Int

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 android.service.personalcontext.understander.UnderstandResult.Builder#setVisualizerSession 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 android.app.personalcontext.PersonalContextManager.UnderstanderType#UNDERSTANDER_TYPE_AGENT.

Value: 32

DESTINATION_NOTIFICATION

Added in API level 37.2
static val DESTINATION_NOTIFICATION: Int

Destination for suggestion chips in notifications. This destination only accepts a android.app.personalcontext.insight.NotificationInsight.

Value: 2

DESTINATION_REMOTE_AUTOFILL

Added in API level 37.2
static val DESTINATION_REMOTE_AUTOFILL: Int

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 android.app.personalcontext.insight.ScreenWhisperAutofillInsight.

Value: 8

DESTINATION_SCREEN_WHISPER

Added in API level 37.2
static val DESTINATION_SCREEN_WHISPER: Int

Destination for screen whispers in the status bar. This destination only accepts a android.app.personalcontext.insight.ScreenWhisperInsight.

Value: 4

DESTINATION_UNIVERSAL

Added in API level 37.2
static val DESTINATION_UNIVERSAL: Int

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 android.app.personalcontext.PersonalContextManager.UnderstanderType#UNDERSTANDER_TYPE_OEM.

Value: 1

DESTINATION_UNKNOWN

Added in API level 37.2
static val DESTINATION_UNKNOWN: Int

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

Value: 0

EXTRA_FEEDBACK_REQUEST

Added in API level 37.2
static val EXTRA_FEEDBACK_REQUEST: String

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

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

EXTRA_PROMPT_REQUEST

Added in API level 37.2
static val EXTRA_PROMPT_REQUEST: String

Intent Extra: The PromptRequest associated with a prompt.

This is a PromptRequest extra.

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

PERSONAL_CONTEXT_SERVICE

Added in API level 37.2
static val PERSONAL_CONTEXT_SERVICE: String

The name of the Personal Context service.

Value: "personal_context"

UNDERSTANDER_TYPE_AGENT

Added in API level 37.2
static val UNDERSTANDER_TYPE_AGENT: Int

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

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

Value: 1

UNDERSTANDER_TYPE_OEM

Added in API level 37.2
static val UNDERSTANDER_TYPE_OEM: Int

Understander type for a personal context understander that is provided by the device manufacturer, implementing 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, android.service.personalcontext.understander.UnderstandRequest#getSessionId will return null.

Value: 2

UNDERSTANDER_TYPE_UNKNOWN

Added in API level 37.2
static val UNDERSTANDER_TYPE_UNKNOWN: Int

Unknown understander type.

Value: 0

Public methods

getEnabledUnderstanders

Added in API level 37.2
fun getEnabledUnderstanders(): MutableList<ComponentName!>

Returns the list of enabled personal context understanders.

Return
MutableList<ComponentName!> The list of currently enabled understanders.
This value cannot be null.

isEnabled

Added in API level 37.2
fun isEnabled(): Boolean

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

isPersonalContextModeEnabled

Added in API level 37.2
fun isPersonalContextModeEnabled(): Boolean

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.

isPersonalContextModeEnabled

Added in API level 37.2
fun isPersonalContextModeEnabled(packageName: String): Boolean

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 android.Manifest.permission#QUERY_ALL_PACKAGES.

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

registerOnPersonalContextEnabledChangedListener

Added in API level 37.2
fun registerOnPersonalContextEnabledChangedListener(
    executor: Executor, 
    listener: Runnable
): Unit

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 API level 37.2
fun registerOnPersonalContextModeChangedListener(
    packageName: String, 
    executor: Executor, 
    listener: PersonalContextManager.OnPersonalContextModeChangedListener
): Unit

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.
Exceptions
java.lang.SecurityException if the caller cannot query the personal context mode for the specified package

registerOnPersonalContextModeChangedListener

Added in API level 37.2
fun registerOnPersonalContextModeChangedListener(
    executor: Executor, 
    listener: PersonalContextManager.OnPersonalContextModeChangedListener
): Unit

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 API level 37.2
fun registerUnderstanderCallback(
    executor: Executor, 
    callback: Runnable
): Unit

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 API level 37.2
fun respondToPrompt(promptResponse: PromptResponse): Unit

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 API level 37.2
fun respondToUnderstanderRegistrationRequest(response: RegistrationResponse): Unit

Responds to an understander registration request.

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

unregisterOnPersonalContextEnabledChangedListener

Added in API level 37.2
fun unregisterOnPersonalContextEnabledChangedListener(listener: Runnable): Unit

Unregisters a listener previously registered with registerOnPersonalContextEnabledChangedListener.

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

unregisterOnPersonalContextModeChangedListener

Added in API level 37.2
fun unregisterOnPersonalContextModeChangedListener(listener: PersonalContextManager.OnPersonalContextModeChangedListener): Unit

Unregisters a listener previously registered with #registerOnPersonalContextModeChangedListener.

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

unregisterUnderstanderCallback

Added in API level 37.2
fun unregisterUnderstanderCallback(callback: Runnable): Unit

Unregisters a previously registered callback.

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