ContentCaptureSession
abstract class ContentCaptureSession : AutoCloseable
| kotlin.Any | |
| ↳ | android.view.contentcapture.ContentCaptureSession |
Session used when notifying the Android system about events associated with views.
Summary
| Constants | |
|---|---|
| static Int |
Content Capture Version 1. |
| static Int |
Content Capture Version 2. |
| Public methods | |
|---|---|
| open Unit |
close()Closes this resource, relinquishing any underlying resources. |
| ContentCaptureSession |
Creates a new |
| Unit |
destroy()Destroys this session, flushing out all pending notifications to the service. |
| open Unit |
flush()Flushes an internal buffer of UI events and signals System Intelligence (SI) that a semantically meaningful state has been reached. |
| ContentCaptureContext? |
Gets the |
| ContentCaptureSessionId |
Gets the id used to identify this session. |
| abstract Int |
Gets the Content Capture version enabled for this session. |
| open AutofillId |
newAutofillId(hostId: AutofillId, virtualChildId: Long)Creates a new |
| ViewStructure |
newViewStructure(view: View)Creates a |
| ViewStructure |
newVirtualViewStructure(parentId: AutofillId, virtualId: Long)Creates a |
| open Unit |
notifyContentInteractionEvent(autofillId: AutofillId)Notifies the Intelligence Service that a view has been interacted. |
| abstract Unit |
notifyNodeAppearedOrChanged(id: AutofillId, properties: ContentCaptureNodeProperties?)Creates a new node or updates an existing one according to the changes in properties. |
| abstract Unit |
Removes a node from the active content capture hierarchy. |
| Unit |
Notifies the Content Capture Service that a session has paused. |
| Unit |
Notifies the Content Capture Service that a session has resumed. |
| Unit |
notifyViewAppeared(node: ViewStructure)Notifies the Content Capture Service that a node has been added to the view structure. |
| Unit |
Notifies the Content Capture Service that a node has been removed from the view structure. |
| Unit |
notifyViewInsetsChanged(viewInsets: Insets)Notifies the Intelligence Service that the insets of a view have changed. |
| Unit |
notifyViewTextChanged(id: AutofillId, text: CharSequence?)Notifies the Intelligence Service that the value of a text node has been changed. |
| Unit |
notifyViewsAppeared(appearedNodes: MutableList<ViewStructure!>)Notifies the Content Capture Service that a list of nodes has appeared in the view structure. |
| Unit |
notifyViewsDisappeared(hostId: AutofillId, virtualIds: LongArray)Notifies the Content Capture Service that many nodes has been removed from a virtual view structure. |
| Unit |
setContentCaptureContext(context: ContentCaptureContext?)Sets the |
| open String |
toString()Returns a string representation of the object. |
Constants
VERSION_1
static val VERSION_1: Int
Content Capture Version 1.
The first Content Capture version is an information rich, event based system that attempts to transfer the current view hierarchy from the application process to a system intelligence service through periodic event dumps, e.g. flush(). However, this system can also be resource heavy due to the large number of events it generates.
When this version is returned by getContentCaptureVersion(), developers should use Version 1 APIs to notify the system of view hierarchy changes. Calling Version 2 APIs when the session is configured for Version 1 will result in no-ops.
A list of functions that belong explicitly to Content Capture Version 1:
notifyViewAppeared(ViewStructure)notifyViewDisappeared(AutofillId)notifyViewsAppeared(List)notifyViewsDisappeared(AutofillId,long[])notifyViewTextChanged(AutofillId,CharSequence)flush()newViewStructure(View)newVirtualViewStructure(AutofillId,long)
Value: 1See Also
VERSION_2
static val VERSION_2: Int
Content Capture Version 2.
The second and newer Content Capture takes a more focused and leaner approach to passing the view hierarchy from the application to a system intelligence service. The required information is mostly limited to text on screen and bounding boxes of these text nodes. This version of Content Capture is also significantly more efficient at resource usage and recommended to be the default one for various system intelligence services to use.
When this version is returned by getContentCaptureVersion(), developers should use Version 2 APIs to report node lifecycle and property updates. Calling Version 1 APIs when the session is configured for Version 2 will result in no-ops.
A list of functions that belong explicitly to Content Capture Version 2:
notifyNodeAppearedOrChanged(AutofillId,ContentCaptureNodeProperties)notifyNodeDisappeared(AutofillId)
Value: 2See Also
Public methods
close
open fun close(): Unit
Closes this resource, relinquishing any underlying resources. This method is invoked automatically on objects managed by the try-with-resources statement.
| Exceptions | |
|---|---|
java.lang.Exception |
if this resource cannot be closed |
createContentCaptureSession
fun createContentCaptureSession(context: ContentCaptureContext): ContentCaptureSession
Creates a new ContentCaptureSession.
See View.setContentCaptureSession(ContentCaptureSession) for more info.
| Parameters | |
|---|---|
context |
ContentCaptureContext: This value cannot be null. |
| Return | |
|---|---|
ContentCaptureSession |
This value cannot be null. |
destroy
fun destroy(): Unit
Destroys this session, flushing out all pending notifications to the service.
Once destroyed, any new notification will be dropped.
flush
open fun flush(): Unit
Flushes an internal buffer of UI events and signals System Intelligence (SI) that a semantically meaningful state has been reached. SI uses this signal to potentially rebuild the view hierarchy and understand the current state of the UI.
UI events are often batched together for performance reasons. A semantic batch represents a series of events that, when applied sequentially, result in a meaningful and complete UI state.
It is crucial to call flush() after completing a semantic batch to ensure SI can accurately reconstruct the view hierarchy.
Premature Flushing: Calling flush() within a semantic batch may lead to SI failing to rebuild the view hierarchy correctly. This could manifest as incorrect ordering of sibling nodes.
Delayed Flushing: While not immediately flushing after a semantic batch is generally safe, it's recommended to do so as soon as possible. In the worst-case scenario where a flush() is never called, SI will attempt to process the events after a short delay based on view appearance and disappearance events.
Note; This function belongs to Content Capture Version 1.
See Also
getContentCaptureContext
fun getContentCaptureContext(): ContentCaptureContext?
Gets the ContentCaptureContext associated with the session.
| Return | |
|---|---|
ContentCaptureContext? |
context set on constructor or by setContentCaptureContext(ContentCaptureContext), or null if never explicitly set. |
getContentCaptureSessionId
fun getContentCaptureSessionId(): ContentCaptureSessionId
Gets the id used to identify this session.
| Return | |
|---|---|
ContentCaptureSessionId |
This value cannot be null. |
getContentCaptureVersion
abstract fun getContentCaptureVersion(): Int
Gets the Content Capture version enabled for this session.
ContentCaptureSession offers two versions: VERSION_1 (legacy event-based capture using ViewStructure) and VERSION_2 (leaner, buffer-backed capture focused on text and bounding boxes).
The returned version is decided by the system intelligence service that coordinates this ContentCaptureSession.
| Return | |
|---|---|
Int |
the enabled version, either VERSION_1 or VERSION_2. Calls to Version 1 methods become no-ops if the returned version is not VERSION_1, and calls to Version 2 methods become no-ops if the returned version is not VERSION_2. Value is one of the following: |
See Also
newAutofillId
open fun newAutofillId(
hostId: AutofillId,
virtualChildId: Long
): AutofillId
Creates a new AutofillId for a virtual child, so it can be used to uniquely identify the children in the session.
| Parameters | |
|---|---|
hostId |
AutofillId: id of the non-virtual view hosting the virtual view hierarchy (it can be obtained by calling ViewStructure.getAutofillId()). This value cannot be null. |
virtualChildId |
Long: id of the virtual child, relative to the parent. |
| Return | |
|---|---|
AutofillId |
if for the virtual child. This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if the parentId is a virtual child id. |
newViewStructure
fun newViewStructure(view: View): ViewStructure
Creates a ViewStructure for a "standard" view.
This method should be called after a visible view is laid out; the view then must populate the structure and pass it to notifyViewAppeared(ViewStructure). Note: views that manage a virtual structure under this view must populate just the node representing this view and return right away, then asynchronously report (not necessarily in the UI thread) when the children nodes appear, disappear or have their text changed by calling ContentCaptureSession.notifyViewAppeared(ViewStructure), ContentCaptureSession.notifyViewDisappeared(AutofillId), and ContentCaptureSession.notifyViewTextChanged(AutofillId,CharSequence) respectively. The structure for the a child must be created using ContentCaptureSession.newVirtualViewStructure(AutofillId,long), and the autofillId for a child can be obtained either through childStructure.getAutofillId() or ContentCaptureSession.newAutofillId(AutofillId,long).
When the virtual view hierarchy represents a web page, you should also:
- Call
ContentCaptureManager.getContentCaptureConditions()to infer content capture events should be generate for that URL. - Create a new
ContentCaptureSessionchild for every HTML element that renders a new URL (like anIFRAME) and use that session to notify events from that subtree.
Note: the following methods of the structure will be ignored:
ViewStructure.setChildCount(int)ViewStructure.addChildCount(int)ViewStructure.getChildCount()ViewStructure.newChild(int)ViewStructure.asyncNewChild(int)ViewStructure.asyncCommit()ViewStructure.setWebDomain(String)ViewStructure.newHtmlInfoBuilder(String)ViewStructure.setHtmlInfo(android.view.ViewStructure.HtmlInfo)ViewStructure.setDataIsSensitive(boolean)ViewStructure.setAlpha(float)ViewStructure.setElevation(float)ViewStructure.setTransformation(android.graphics.Matrix)
Note: This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
view |
View: This value cannot be null. |
| Return | |
|---|---|
ViewStructure |
This value cannot be null. |
See Also
newVirtualViewStructure
fun newVirtualViewStructure(
parentId: AutofillId,
virtualId: Long
): ViewStructure
Creates a ViewStructure for a "virtual" view, so it can be passed to notifyViewAppeared(ViewStructure) by the view managing the virtual view hierarchy.
Note: This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
parentId |
AutofillId: id of the virtual view parent (it can be obtained by calling ViewStructure.getAutofillId() on the parent). This value cannot be null. |
virtualId |
Long: id of the virtual child, relative to the parent. |
| Return | |
|---|---|
ViewStructure |
a new ViewStructure that can be used for Content Capture purposes. This value cannot be null. |
notifyContentInteractionEvent
open fun notifyContentInteractionEvent(autofillId: AutofillId): Unit
Notifies the Intelligence Service that a view has been interacted.
The view must have appeared before sending the interaction event.
| Parameters | |
|---|---|
autofillId |
AutofillId: id of the node. This value cannot be null. |
notifyNodeAppearedOrChanged
abstract fun notifyNodeAppearedOrChanged(
id: AutofillId,
properties: ContentCaptureNodeProperties?
): Unit
Creates a new node or updates an existing one according to the changes in properties.
This is the primary method to construct and report the UI hierarchy in Content Capture Version 2. It unifies the reporting of both standard Views and virtual views (e.g., inside a Webview) into a single, cohesive API. Call this method when a node is attached, laid out, and ready to be drawn in the active UI hierarchy, or when its properties (like text or bounds) change.
For standard views, the id can be obtained via View.getAutofillId(). For virtual views, the id must be created using newAutofillId(AutofillId,long).
To minimize memory allocations, applications should reuse a single ContentCaptureNodeProperties instance, calling ContentCaptureNodeProperties.clear() before populating it for a new node.
If the node already exists, only the properties explicitly set in the ContentCaptureNodeProperties payload will be updated. The parent-child relationship is modified based on the parent ID configuration:
- Setting parent ID to
null: Guarantees that this node is treated as a root node with no parent. - Not setting parent ID at all: Leaves the existing parent unchanged. If the node is appearing for the first time, it defaults to a root node.
Note: This function belongs to Content Capture Version 2.
.This method must be called on the thread that originally created this UI element. This is typically the main thread of your app.
| Parameters | |
|---|---|
id |
AutofillId: The AutofillId of the node. This value cannot be null. |
properties |
ContentCaptureNodeProperties?: The ContentCaptureNodeProperties holding the attributes for this node. This value may be null. |
notifyNodeDisappeared
abstract fun notifyNodeDisappeared(id: AutofillId): Unit
Removes a node from the active content capture hierarchy.
This is the primary method to report the removal of UI components in Content Capture Version 2. It applies to both standard Views and virtual views, signaling that the node is no longer part of the visible hierarchy.
When a node is deleted:
- Its internal resources (such as text and content description allocations) are freed.
- Its children are orphaned and promoted to root nodes (their parent pointer is cleared). If you want to remove an entire subtree, you must recursively call this method for all descendant nodes in the subtree. Re-adding this node will not automatically relink previous children.
Note; This function belongs to Content Capture Version 2.
.This method must be called on the thread that originally created this UI element. This is typically the main thread of your app.
| Parameters | |
|---|---|
id |
AutofillId: The AutofillId of the node to delete. This value cannot be null. |
notifySessionPaused
fun notifySessionPaused(): Unit
Notifies the Content Capture Service that a session has paused.
notifySessionResumed
fun notifySessionResumed(): Unit
Notifies the Content Capture Service that a session has resumed.
notifyViewAppeared
fun notifyViewAppeared(node: ViewStructure): Unit
Notifies the Content Capture Service that a node has been added to the view structure.
Typically called "manually" by views that handle their own virtual view hierarchy, or automatically by the Android System for views that return true on View.onProvideContentCaptureStructure(ViewStructure,int).
Consider use notifyViewsAppeared which has a better performance when notifying a list of nodes has appeared.
Note; This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
node |
ViewStructure: node that has been added. This value cannot be null. |
notifyViewDisappeared
fun notifyViewDisappeared(id: AutofillId): Unit
Notifies the Content Capture Service that a node has been removed from the view structure.
Typically called "manually" by views that handle their own virtual view hierarchy, or automatically by the Android System for standard views.
Consider use notifyViewsDisappeared which has a better performance when notifying a list of nodes has disappeared.
Note; This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
id |
AutofillId: id of the node that has been removed. This value cannot be null. |
See Also
notifyViewInsetsChanged
fun notifyViewInsetsChanged(viewInsets: Insets): Unit
Notifies the Intelligence Service that the insets of a view have changed.
| Parameters | |
|---|---|
viewInsets |
Insets: This value cannot be null. |
notifyViewTextChanged
fun notifyViewTextChanged(
id: AutofillId,
text: CharSequence?
): Unit
Notifies the Intelligence Service that the value of a text node has been changed.
Note; This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
id |
AutofillId: of the node. This value cannot be null. |
text |
CharSequence?: new text. This value may be null. |
notifyViewsAppeared
fun notifyViewsAppeared(appearedNodes: MutableList<ViewStructure!>): Unit
Notifies the Content Capture Service that a list of nodes has appeared in the view structure.
Typically called manually by views that handle their own virtual view hierarchy.
Note; This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
appearedNodes |
MutableList<ViewStructure!>: nodes that have appeared. Each element represents a view node that has been added to the view structure. The order of the elements is important, which should be preserved as the attached order of when the node is attached to the virtual view hierarchy. This value cannot be null. |
See Also
notifyViewsDisappeared
fun notifyViewsDisappeared(
hostId: AutofillId,
virtualIds: LongArray
): Unit
Notifies the Content Capture Service that many nodes has been removed from a virtual view structure.
Should only be called by views that handle their own virtual view hierarchy.
After UPSIDE_DOWN_CAKE, this method wraps the virtual children with a pair of view tree appearing and view tree appeared events.
Note; This function belongs to Content Capture Version 1.
| Parameters | |
|---|---|
hostId |
AutofillId: id of the non-virtual view hosting the virtual view hierarchy (it can be obtained by calling ViewStructure.getAutofillId()). This value cannot be null. |
virtualIds |
LongArray: ids of the virtual children. This value cannot be null. |
| Exceptions | |
|---|---|
java.lang.IllegalArgumentException |
if virtualIds is empty |
See Also
setContentCaptureContext
fun setContentCaptureContext(context: ContentCaptureContext?): Unit
Sets the ContentCaptureContext associated with the session.
Typically used to change the context associated with the default session from an activity.
| Parameters | |
|---|---|
context |
ContentCaptureContext?: This value may be null. |
toString
open fun toString(): String
Returns a string representation of the object.
| Return | |
|---|---|
String |
a string representation of the object. |