Added in version 37.2

Summary: Constants | Methods | Inherited Methods

InsightVisualizerSession

Kotlin |Java

public interface InsightVisualizerSession
implements 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 (ERROR(PersonalContextManager.DESTINATION_EMBEDDED/android.service.personalcontext.PersonalContextManager#DESTINATION_EMBEDDED 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(Set, InsightVisualizerClientConfig) 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
`int`	`CLOSE_REASON_CLIENT_DISCONNECTED` Close reason when the client application releases or disconnects from the visualization.
`int`	`CLOSE_REASON_ERROR` Close reason when an unrecoverable rendering, IPC, or system error occurs.
`int`	`CLOSE_REASON_UNKNOWN` Close reason when the session end reason is unknown.
`int`	`CLOSE_REASON_USER_BUTTON_PRESS` Close reason when the user triggers a close action attached to a button in the visualization.
`int`	`CLOSE_REASON_VISUALIZER_DECISION` Close reason when the visualizer or understander decides to end the visualization session.

Public methods
`default void`	`close(int reason)` Ends the visualization session permanently.
`abstract void`	`close()` Ends the visualization session permanently.
`abstract RemoteViews`	`createRemoteViewsForHints(Set<ContextHint> hints, InsightVisualizerClientConfig config)` Requests a `RemoteViews` visualization for the given set of hints and configuration.

Inherited methods

From interface


        
          java.lang.AutoCloseable


      close()

Closes this resource, relinquishing any underlying resources.

Constants

CLOSE_REASON_CLIENT_DISCONNECTED

Added in version 37.2

public static final int CLOSE_REASON_CLIENT_DISCONNECTED

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

Constant Value: 2 (0x00000002)

CLOSE_REASON_ERROR

Added in version 37.2

public static final int CLOSE_REASON_ERROR

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

Constant Value: 4 (0x00000004)

CLOSE_REASON_UNKNOWN

Added in version 37.2

public static final int CLOSE_REASON_UNKNOWN

Close reason when the session end reason is unknown.

Constant Value: 0 (0x00000000)

CLOSE_REASON_USER_BUTTON_PRESS

Added in version 37.2

public static final int CLOSE_REASON_USER_BUTTON_PRESS

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

Constant Value: 1 (0x00000001)

CLOSE_REASON_VISUALIZER_DECISION

Added in version 37.2

public static final int CLOSE_REASON_VISUALIZER_DECISION

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

Constant Value: 3 (0x00000003)

Public methods

close

Added in version 37.2

public void close (int reason)

Ends the visualization session permanently. The visualization will no longer be shown in the client app and no more createRemoteViewsForHints(Set, InsightVisualizerClientConfig) 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: `CLOSE_REASON_UNKNOWN` `CLOSE_REASON_USER_BUTTON_PRESS` `CLOSE_REASON_CLIENT_DISCONNECTED` `CLOSE_REASON_VISUALIZER_DECISION` `CLOSE_REASON_ERROR`

close

Added in version 37.2

public abstract void close ()

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

createRemoteViewsForHints

Added in version 37.2

public abstract RemoteViews createRemoteViewsForHints (Set<ContextHint> hints, 
                InsightVisualizerClientConfig config)

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

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`	`Set`: 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`.

Returns
`RemoteViews`	the `RemoteViews` containing the visualization, or null if a visualization cannot be generated