Added in API level 37.2

InsightVisualizerSession

interface InsightVisualizerSession : AutoCloseable
android.service.personalcontext.embedded.InsightVisualizerSession

Interface representing an active interactive visualization session with a client application.

When a client app requests a visualization for the first time, ContextUnderstanderService.onUnderstand(UnderstandRequest) will include an embedded destination (PersonalContextManager.DESTINATION_EMBEDDED). In response, the understander may return an instance of this class in UnderstandResult.Builder.setVisualizerSession if it wants to generate visualizations for this client.

If a InsightVisualizerSession is not returned, the client session will be terminated.

Once the session is established, additional hints from the client app will route directly to createRemoteViewsForHints and bypass ContextUnderstanderService.onUnderstand.

This session is live from the time it was created until #close is called, after which no more visualizations will be requested.

All calls on this session will be executed on the Executor configured via ContextUnderstanderService.setExecutor, or on the main looper by default.

Summary

Constants
static Int

Close reason when the client application releases or disconnects from the visualization.
static Int

Close reason when an unrecoverable rendering, IPC, or system error occurs.
static Int

Close reason when the session end reason is unknown.
static Int

Close reason when the user triggers a close action attached to a button in the visualization.
static Int

Close reason when the visualizer or understander decides to end the visualization session.
Public methods
abstract Unit

Ends the visualization session permanently.
open Unit
close(reason: Int)

Ends the visualization session permanently.
abstract RemoteViews?

Requests a RemoteViews visualization for the given set of hints and configuration.

Constants

CLOSE_REASON_CLIENT_DISCONNECTED

Added in API level 37.2
static val CLOSE_REASON_CLIENT_DISCONNECTED: Int

Close reason when the client application releases or disconnects from the visualization.

Value: 2

CLOSE_REASON_ERROR

Added in API level 37.2
static val CLOSE_REASON_ERROR: Int

Close reason when an unrecoverable rendering, IPC, or system error occurs.

Value: 4

CLOSE_REASON_UNKNOWN

Added in API level 37.2
static val CLOSE_REASON_UNKNOWN: Int

Close reason when the session end reason is unknown.

Value: 0

CLOSE_REASON_USER_BUTTON_PRESS

Added in API level 37.2
static val CLOSE_REASON_USER_BUTTON_PRESS: Int

Close reason when the user triggers a close action attached to a button in the visualization.

Value: 1

CLOSE_REASON_VISUALIZER_DECISION

Added in API level 37.2
static val CLOSE_REASON_VISUALIZER_DECISION: Int

Close reason when the visualizer or understander decides to end the visualization session.

Value: 3

Public methods

close

Added in API level 37.2
abstract fun close(): Unit

Ends the visualization session permanently. The visualization will no longer be shown in the client app and no more createRemoteViewsForHints calls will be made after this call.

Calling this method after the session is closed has no effect.

Exceptions
java.lang.Exception if this resource cannot be closed

close

Added in API level 37.2
open fun close(reason: Int): Unit

Ends the visualization session permanently. The visualization will no longer be shown in the client app and no more createRemoteViewsForHints calls will be made after this call.

Calling this method after the session is closed has no effect.

Parameters
reason Int: the reason why this visualization session was closed.
Value is one of the following:

createRemoteViewsForHints

Added in API level 37.2
abstract fun createRemoteViewsForHints(
    hints: MutableSet<ContextHint!>, 
    config: InsightVisualizerClientConfig
): RemoteViews?

Requests a RemoteViews visualization for the given set of hints and configuration.

This method is invoked upon initial connection, and will be called again when additional hints arrive or client configuration changes. This method will not be called multiple times concurrently for a given session.

The returned RemoteViews will be embedded in a android.view.SurfaceControlViewHost for display in the client app. The client app provides the maximum available space using InsightVisualizerClientConfig.getMaximumHeight() and InsightVisualizerClientConfig.getMaximumWidth(). The visualizer cannot use more than the available height or the visualization will be cut off. If the visualizer uses more than the available width, the resulting visualization will scroll horizontally in the available width.

The returned RemoteViews will be displayed in the client app until the client ends the session and #close is received, or until another call is made to this method.

android.content.res.Configuration changes, such as theme or font size, are automatically applied to the RemoteViews. Nested scrolling events will be automatically passed to the client app by the framework.

To trigger personal context functionality like egressing insights when individual views in the visualization are clicked, the visualizer can attach actions to views using VisualizerViewAction.attach or by calling RemoteViews.setOnClickPendingIntent with the intent from VisualizerViewAction.createIntent. Any intents directly attached with RemoteViews.setOnClickPendingIntent will not be run on click.

If the visualizer is unable to generate a visualization for the given hints and configuration, returning null will end the session.

Parameters
hints MutableSet<ContextHint!>: the set of hints to generate a visualization for.
This value cannot be null.
config InsightVisualizerClientConfig: the client surface configuration and sizing constraints.
This value cannot be null.
Return
RemoteViews? the RemoteViews containing the visualization, or null if a visualization cannot be generated