import android.annotation.NonNull;
import android.os.Parcel;
import android.os.Parcelable;
+import android.view.contentcapture.ContentCaptureManager;
import com.android.internal.util.Preconditions;
import java.io.PrintWriter;
/**
- * Identifier for an unique state in the application.
+ * An identifier for an unique state (locus) in the application. Should be stable across reboots and
+ * backup / restore.
*
- * <p>Should be stable across reboots and backup / restore.
+ * <p>Locus is a new concept introduced on
+ * {@link android.os.Build.VERSION_CODES#Q Android Q} and it lets the intelligence service provided
+ * by the Android System to correlate state between different subsystems such as content capture,
+ * shortcuts, and notifications.
*
- * <p>For example, a chat app could use the context to resume a conversation between 2 users.
+ * <p>For example, if your app provides an activiy representing a chat between 2 users
+ * (say {@code A} and {@code B}, this chat state could be represented by:
+ *
+ * <pre><code>
+ * LocusId chatId = new LocusId("Chat_A_B");
+ * </code></pre>
+ *
+ * <p>And then you should use that {@code chatId} by:
+ *
+ * <ul>
+ * <li>Setting it in the chat notification (through
+ * {@link android.app.Notification.Builder#setLocusId(LocusId)
+ * Notification.Builder.setLocusId(chatId)}).
+ * <li>Setting it into the {@link android.content.pm.ShortcutInfo} (through
+ * {@link android.content.pm.ShortcutInfo.Builder#setLocusId(LocusId)
+ * ShortcutInfo.Builder.setLocusId(chatId)}), if you provide a launcher shortcut for that chat
+ * conversation.
+ * <li>Associating it with the {@link android.view.contentcapture.ContentCaptureContext} of the
+ * root view of the chat conversation activity (through
+ * {@link android.view.View#getContentCaptureSession()}, then
+ * {@link android.view.contentcapture.ContentCaptureContext.Builder
+ * new ContentCaptureContext.Builder(chatId).build()} and
+ * {@link android.view.contentcapture.ContentCaptureSession#setContentCaptureContext(
+ * android.view.contentcapture.ContentCaptureContext)} - see {@link ContentCaptureManager}
+ * for more info about content capture).
+ * <li>Configuring your app to launch the chat conversation through the
+ * {@link Intent#ACTION_VIEW_LOCUS} intent.
+ * </ul>
*/
-// TODO(b/123577059): make sure this is well documented and understandable
public final class LocusId implements Parcelable {
private final String mId;
}
/**
- * Gets the {@code id} associated with the locus.
+ * Gets the canonical {@code id} associated with the locus.
*/
@NonNull
public String getId() {
parcel.writeString(mId);
}
- public static final @android.annotation.NonNull Parcelable.Creator<LocusId> CREATOR =
+ public static final @NonNull Parcelable.Creator<LocusId> CREATOR =
new Parcelable.Creator<LocusId>() {
@NonNull
}
/**
- * Populates a {@link ViewStructure} for Content Capture.
+ * Populates a {@link ViewStructure} for content capture.
*
- * <p>This method is called after a view is that is eligible for Content Capture
+ * <p>This method is called after a view is that is eligible for content capture
* (for example, if it {@link #isImportantForAutofill()}, an intelligence service is enabled for
- * the user, and the activity rendering the view is enabled for Content Capture) is laid out and
+ * the user, and the activity rendering the view is enabled for content capture) is laid out and
* is visible.
*
* <p>The populated structure is then passed to the service through
* {@code childStructure.getAutofillId()} or
* {@link ContentCaptureSession#newAutofillId(AutofillId, long)}.
*
+ * <p>When the virtual view hierarchy represents a web page, you should also:
+ *
+ * <ul>
+ * <li>Call {@link ContentCaptureManager#getContentCaptureConditions()} to infer content
+ * capture events should be generate for that URL.
+ * <li>Create a new {@link ContentCaptureSession} child for every HTML element that
+ * renders a new URL (like an {@code IFRAME}) and use that session to notify events from
+ * that subtree.
+ * </ul>
+ *
* <p><b>Note: </b>the following methods of the {@code structure} will be ignored:
* <ul>
* <li>{@link ViewStructure#setChildCount(int)}
}
/**
- * Hints the Android System whether this view is considered important for Content Capture, based
+ * Hints the Android System whether this view is considered important for content capture, based
* on the value explicitly set by {@link #setImportantForContentCapture(int)} and heuristics
* when it's {@link #IMPORTANT_FOR_CONTENT_CAPTURE_AUTO}.
*
- * @return whether the view is considered important for autofill.
+ * <p>See {@link ContentCaptureManager} for more info about content capture.
+ *
+ * @return whether the view is considered important for content capture.
*
* @see #setImportantForContentCapture(int)
* @see #IMPORTANT_FOR_CONTENT_CAPTURE_AUTO
* Sets the (optional) {@link ContentCaptureSession} associated with this view.
*
* <p>This method should be called when you need to associate a {@link ContentCaptureContext} to
- * the Content Capture events associated with this view or its view hierarchy (if it's a
+ * the content capture events associated with this view or its view hierarchy (if it's a
* {@link ViewGroup}).
*
* <p>For example, if your activity is associated with a web domain, first you would need to
}
/**
- * Gets the session used to notify Content Capture events.
+ * Gets the session used to notify content capture events.
*
* @return session explicitly set by {@link #setContentCaptureSession(ContentCaptureSession)},
* inherited by ancestors, default session or {@code null} if content capture is disabled for
}
/**
- * Dispatches the initial Content Capture events for a view structure.
+ * Dispatches the initial content capture events for a view structure.
*
* @hide
*/
import android.content.ComponentName;
import android.content.ContentCaptureOptions;
import android.content.Context;
+import android.graphics.Canvas;
import android.os.Handler;
import android.os.IBinder;
import android.os.Looper;
import android.os.RemoteException;
import android.os.ServiceManager;
import android.util.Log;
+import android.view.View;
+import android.view.ViewStructure;
import android.view.contentcapture.ContentCaptureSession.FlushReason;
import com.android.internal.annotations.GuardedBy;
import java.util.Set;
/**
- * TODO(b/123577059): add javadocs / mention it can be null
+ * <p>The {@link ContentCaptureManager} provides additional ways for for apps to
+ * integrate with the content capture subsystem.
+ *
+ * <p>Content capture provides real-time, continuous capture of application activity, display and
+ * events to an intelligence service that is provided by the Android system. The intelligence
+ * service then uses that info to mediate and speed user journey through different apps. For
+ * example, when the user receives a restaurant address in a chat app and switchs to a map app
+ * to search for that restaurant, the intelligence service could offer an autofill dialog to
+ * let the user automatically select its address.
+ *
+ * <p>Content capture was designed with two major concerns in mind: privacy and performance.
+ *
+ * <ul>
+ * <li><b>Privacy:</b> the intelligence service is a trusted component provided that is provided
+ * by the device manufacturer and that cannot be changed by the user (although the user can
+ * globaly disable content capture using the Android Settings app). This service can only use the
+ * data for in-device machine learning, which is enforced both by process isolation and
+ * <a href="https://source.android.com/compatibility/cdd">CDD requirements</a>.
+ * <li><b>Performance:</b> content capture is highly optimized to minimize its impact in the app
+ * jankiness and overall device system health. For example, its only enabled on apps (or even
+ * specific activities from an app) that were explicitly whitelisted by the intelligence service,
+ * and it buffers the events so they are sent in a batch to the service (see
+ * {@link #isContentCaptureEnabled()} for other cases when its disabled).
+ * </ul>
+ *
+ * <p>In fact, before using this manager, the app developer should check if it's available. Example:
+ * <code>
+ * ContentCaptureManager mgr = context.getSystemService(ContentCaptureManager.class);
+ * if (mgr != null && mgr.isContentCaptureEnabled()) {
+ * // ...
+ * }
+ * </code>
+ *
+ * <p>App developers usually don't need to explicitly interact with content capture, except when the
+ * app:
+ *
+ * <ul>
+ * <li>Can define a contextual {@link android.content.LocusId} to identify unique state (such as a
+ * conversation between 2 chat users).
+ * <li>Can have multiple view hierarchies with different contextual meaning (for example, a
+ * browser app with multiple tabs, each representing a different URL).
+ * <li>Contains custom views (that extend View directly and are not provided by the standard
+ * Android SDK.
+ * <li>Contains views that provide their own virtual hierarchy (like a web browser that render the
+ * HTML elements using a Canvas).
+ * </ul>
+ *
+ * <p>The main integration point with content capture is the {@link ContentCaptureSession}. A "main"
+ * session is automatically created by the Android System when content capture is enabled for the
+ * activity and its used by the standard Android views to notify the content capture service of
+ * events such as views being added, views been removed, and text changed by user input. The session
+ * could have a {@link ContentCaptureContext} to provide more contextual info about it, such as
+ * the locus associated with the view hierarchy (see {@link android.content.LocusId} for more info
+ * about locus). By default, the main session doesn't have a {@code ContentCaptureContext}, but you
+ * can change it after its created. Example:
+ *
+ * <pre><code>
+ * protected void onCreate(Bundle savedInstanceState) {
+ * // Initialize view structure
+ * ContentCaptureSession session = rootView.getContentCaptureSession();
+ * if (session != null) {
+ * session.setContentCaptureContext(ContentCaptureContext.forLocusId("chat_UserA_UserB"));
+ * }
+ * }
+ * </code></pre>
+ *
+ * <p>If your activity contains view hierarchies with a different contextual meaning, you should
+ * created child sessions for each view hierarchy root. For example, if your activity is a browser,
+ * you could use the main session for the main URL being rendered, then child sessions for each
+ * {@code IFRAME}:
+ *
+ * <pre><code>
+ * ContentCaptureSession mMainSession;
+ *
+ * protected void onCreate(Bundle savedInstanceState) {
+ * // Initialize view structure...
+ * mMainSession = rootView.getContentCaptureSession();
+ * if (mMainSession != null) {
+ * mMainSession.setContentCaptureContext(
+ * ContentCaptureContext.forLocusId("https://example.com"));
+ * }
+ * }
+ *
+ * private void loadIFrame(View iframeRootView, String url) {
+ * if (mMainSession != null) {
+ * ContentCaptureSession iFrameSession = mMainSession.newChild(
+ * ContentCaptureContext.forLocusId(url));
+ * }
+ * iframeRootView.setContentCaptureSession(iFrameSession);
+ * }
+ * // Load iframe...
+ * }
+ * </code></pre>
+ *
+ * <p>If your activity has custom views (i.e., views that extend {@link View} directly and provide
+ * just one logical view, not a virtual tree hiearchy) and it provides content that's relevant for
+ * content capture (as of {@link android.os.Build.VERSION_CODES#Q Android Q}, the only relevant
+ * content is text), then your view implementation should:
+ *
+ * <ul>
+ * <li>Set it as important for content capture.
+ * <li>Fill {@link ViewStructure} used for content capture.
+ * <li>Notify the {@link ContentCaptureSession} when the text is changed by user input.
+ * </ul>
+ *
+ * <p>Here's an example of the relevant methods for an {@code EditText}-like view:
+ *
+ * <pre><code>
+ * public class MyEditText extends View {
+ *
+ * public MyEditText(...) {
+ * if (getImportantForContentCapture() == IMPORTANT_FOR_CONTENT_CAPTURE_AUTO) {
+ * setImportantForContentCapture(IMPORTANT_FOR_CONTENT_CAPTURE_YES);
+ * }
+ * }
+ *
+ * public void onProvideContentCaptureStructure(@NonNull ViewStructure structure, int flags) {
+ * super.onProvideContentCaptureStructure(structure, flags);
+ *
+ * structure.setText(getText(), getSelectionStart(), getSelectionEnd());
+ * structure.setHint(getHint());
+ * structure.setInputType(getInputType());
+ * // set other properties like setTextIdEntry(), setTextLines(), setTextStyle(),
+ * // setMinTextEms(), setMaxTextEms(), setMaxTextLength()
+ * }
+ *
+ * private void onTextChanged() {
+ * if (isLaidOut() && isImportantForContentCapture() && isTextEditable()) {
+ * ContentCaptureManager mgr = mContext.getSystemService(ContentCaptureManager.class);
+ * if (cm != null && cm.isContentCaptureEnabled()) {
+ * ContentCaptureSession session = getContentCaptureSession();
+ * if (session != null) {
+ * session.notifyViewTextChanged(getAutofillId(), getText());
+ * }
+ * }
+ * }
+ * </code></pre>
+ *
+ * <p>If your view provides its own virtual hierarchy (for example, if it's a browser that draws
+ * the HTML using {@link Canvas} or native libraries in a different render process), then the view
+ * is also responsible to notify the session when the virtual elements appear and disappear - see
+ * {@link View#onProvideContentCaptureStructure(ViewStructure, int)} for more info.
*/
@SystemService(Context.CONTENT_CAPTURE_MANAGER_SERVICE)
public final class ContentCaptureManager {
/**
* DeviceConfig property used by {@code com.android.server.SystemServer} on start to decide
- * whether the Content Capture service should be created or not
+ * whether the content capture service should be created or not
*
* <p>By default it should *NOT* be set (or set to {@code "default"}, so the decision is based
* on whether the OEM provides an implementation for the service), but it can be overridden to:
* <p>There are many reasons it could be disabled, such as:
* <ul>
* <li>App itself disabled content capture through {@link #setContentCaptureEnabled(boolean)}.
- * <li>Service disabled content capture for this specific activity.
- * <li>Service disabled content capture for all activities of this package.
- * <li>Service disabled content capture globally.
- * <li>User disabled content capture globally (through Settings).
- * <li>OEM disabled content capture globally.
- * <li>Transient errors.
+ * <li>Intelligence service did not whitelist content capture for this activity's package.
+ * <li>Intelligence service did not whitelist content capture for this specific activity.
+ * <li>Intelligence service disabled content capture globally.
+ * <li>User disabled content capture globally through the Android Settings app.
+ * <li>Device manufacturer (OEM) disabled content capture globally.
+ * <li>Transient errors, such as intelligence service package being updated.
* </ul>
*/
public boolean isContentCaptureEnabled() {
* capture events for websites the content capture service is not interested on.
*
* @return list of conditions, or {@code null} if the service didn't set any restriction
- * (in which case content capture events should always be generated).
+ * (in which case content capture events should always be generated). If the list is empty,
+ * then it should not generate any event at all.
*/
@Nullable
public Set<ContentCaptureCondition> getContentCaptureConditions() {
}
/**
- * Gets whether Content Capture is enabled for the given user.
+ * Gets whether content capture is enabled for the given user.
*
- * <p>This method is typically used by the Content Capture Service settings page, so it can
+ * <p>This method is typically used by the content capture service settings page, so it can
* provide a toggle to enable / disable it.
*
- * @throws SecurityException if caller is not the app that owns the Content Capture service
+ * @throws SecurityException if caller is not the app that owns the content capture service
* associated with the user.
*
* @hide
}
/**
- * Called by the app to request the Content Capture service to remove user-data associated with
+ * Called by the app to request the content capture service to remove user-data associated with
* some context.
*
* @param request object specifying what user data should be removed.
OSDN Git Service
