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

Nested classes

class OnDevicePersonalizationManager.ExecuteResult

The result of a call to OnDevicePersonalizationManager.execute(ComponentName, PersistableBundle, Executor, OutcomeReceiver) 

Public methods

void execute(ComponentName service, PersistableBundle params, Executor executor, OutcomeReceiver<OnDevicePersonalizationManager.ExecuteResult, Exception> receiver)

Executes an IsolatedService in the OnDevicePersonalization sandbox.

void executeInIsolatedService(ExecuteInIsolatedServiceRequest request, Executor executor, OutcomeReceiver<ExecuteInIsolatedServiceResponse, Exception> receiver)

Executes an IsolatedService in the OnDevicePersonalization sandbox.

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.

Inherited methods

Public methods

execute

Added in API level 35 
 public void execute (ComponentName service, PersistableBundle params, Executor executor, OutcomeReceiver<OnDevicePersonalizationManager.ExecuteResult, Exception> receiver)

Executes an IsolatedService in the OnDevicePersonalization sandbox. The platform binds to the specified IsolatedService in an isolated process and calls IsolatedWorker.onExecute(android.adservices.ondevicepersonalization.ExecuteInput, android.os.OutcomeReceiver) 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
service 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 ExecuteResult object on success or an Exception on failure. If the IsolatedService returned a RenderingConfig to be displayed, ExecuteResult.getSurfacePackageToken() will return a non-null SurfacePackageToken. The SurfacePackageToken object 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 returned SurfacePackageToken may be null to indicate that no output is expected to be displayed for this request. If the IsolatedService has returned any output data and the calling app is allowlisted to receive data from this service, the OnDevicePersonalizationManager.ExecuteResult.getOutputData() will return a non-null byte array.

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.

executeInIsolatedService

Added in API level 36 
 public void executeInIsolatedService (ExecuteInIsolatedServiceRequest request, Executor executor, OutcomeReceiver<ExecuteInIsolatedServiceResponse, Exception> receiver)

Executes an IsolatedService in the OnDevicePersonalization sandbox. The platform binds to the specified IsolatedService in an isolated process and calls IsolatedWorker.onExecute(android.adservices.ondevicepersonalization.ExecuteInput, android.os.OutcomeReceiver) 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
request ExecuteInIsolatedServiceRequest: the ExecuteInIsolatedServiceRequest request 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 ExecuteInIsolatedServiceResponse object on success or an Exception on failure. For success case, refer to ExecuteInIsolatedServiceResponse. For error case, the receiver returns an OnDevicePersonalizationException if execution of the handler fails. This value cannot be null.

requestSurfacePackage

Added in API level 35 
 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.