OnDevicePersonalizationManager
public
class
OnDevicePersonalizationManager
extends Object
java.lang.Object | |
↳ | android.adservices.ondevicepersonalization.OnDevicePersonalizationManager |
OnDevicePersonalizationManager provides APIs for apps to load an
IsolatedService
in an isolated process and interact with it.
An app can request an IsolatedService
to generate content for display
within an SurfaceView
within the app's view hierarchy, and also write
persistent results to on-device storage which can be consumed by Federated Analytics for
cross-device statistical analysis or by Federated Learning for model training. The displayed
content and the persistent output are both not directly accessible by the calling app.
Summary
Public methods | |
---|---|
void
|
execute(ComponentName handler, PersistableBundle params, Executor executor, OutcomeReceiver<List<SurfacePackageToken>, Exception> receiver)
Executes an |
void
|
requestSurfacePackage(SurfacePackageToken surfacePackageToken, IBinder surfaceViewHostToken, int displayId, int width, int height, Executor executor, OutcomeReceiver<SurfaceControlViewHost.SurfacePackage, Exception> receiver)
Requests a |
Inherited methods | |
---|---|
Public methods
execute
public void execute (ComponentName handler, PersistableBundle params, Executor executor, OutcomeReceiver<List<SurfacePackageToken>, Exception> receiver)
Executes an IsolatedService
in the OnDevicePersonalization sandbox. The
platform binds to the specified IsolatedService
in an isolated process
and calls IsolatedWorker#onExecute(ExecuteInput, java.util.function.Consumer)
with the caller-provided parameters. When the IsolatedService
finishes execution,
the platform returns tokens that refer to the results from the service to the caller.
These tokens can be subsequently used to display results in a
SurfaceView
within the calling app.
Parameters | |
---|---|
handler |
ComponentName : The ComponentName of the IsolatedService .
This value cannot be null . |
params |
PersistableBundle : a PersistableBundle that is passed from the calling app to the
IsolatedService . The expected contents of this parameter are defined
by theIsolatedService . The platform does not interpret this parameter.
This value cannot be null . |
executor |
Executor : the Executor on which to invoke 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. |
receiver |
OutcomeReceiver : This returns a list of SurfacePackageToken objects, each of which is
an opaque reference to a RenderingConfig returned by an
IsolatedService , or an Exception on failure. The returned
SurfacePackageToken objects can be used in a subsequent
requestSurfacePackage(android.adservices.ondevicepersonalization.SurfacePackageToken, android.os.IBinder, int, int, int, java.util.concurrent.Executor, android.os.OutcomeReceiver) call to display the result in a view. The calling app and
the IsolatedService must agree on the expected size of this list.
An entry in the returned list of SurfacePackageToken objects may be null to
indicate that the service has no output for that specific surface.
In case of an error, the receiver returns one of the following exceptions:
Returns a PackageManager.NameNotFoundException if the handler
package is not installed or does not have a valid ODP manifest.
Returns ClassNotFoundException if the handler class is not found.
Returns an OnDevicePersonalizationException if execution of the handler fails. |
requestSurfacePackage
public void requestSurfacePackage (SurfacePackageToken surfacePackageToken, IBinder surfaceViewHostToken, int displayId, int width, int height, Executor executor, OutcomeReceiver<SurfaceControlViewHost.SurfacePackage, Exception> receiver)
Requests a SurfaceControlViewHost.SurfacePackage
to be inserted into a
SurfaceView
inside the calling app. The surface package will contain an
View
with the content from a result of a prior call to
#execute(ComponentName, PersistableBundle, Executor, OutcomeReceiver)
running in
the OnDevicePersonalization sandbox.
Parameters | |
---|---|
surfacePackageToken |
SurfacePackageToken : a reference to a SurfacePackageToken returned by a prior
call to #execute(ComponentName, PersistableBundle, Executor, OutcomeReceiver) .
This value cannot be null . |
surfaceViewHostToken |
IBinder : the hostToken of the SurfaceView , which is
returned by SurfaceView.getHostToken() after the
SurfaceView has been added to the view hierarchy.
This value cannot be null . |
displayId |
int : the integer ID of the logical display on which to display the
SurfaceControlViewHost.SurfacePackage , returned by
Context.getDisplay().getDisplayId() . |
width |
int : the width of the SurfaceControlViewHost.SurfacePackage
in pixels. |
height |
int : the height of the SurfaceControlViewHost.SurfacePackage
in pixels. |
executor |
Executor : the Executor on which to invoke 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. |
receiver |
OutcomeReceiver : This either returns a
SurfaceControlViewHost.SurfacePackage on success, or
Exception on failure. The exception type is
OnDevicePersonalizationException if execution of the handler fails.
This value cannot be null . |