Added in API level 35

OnDevicePersonalizationManager


open class OnDevicePersonalizationManager
kotlin.Any
   ↳ 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 android.view.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
open

The result of a call to OnDevicePersonalizationManager#execute(ComponentName,

Public methods
open Unit

Executes an IsolatedService in the OnDevicePersonalization sandbox.

open Unit
requestSurfacePackage(surfacePackageToken: SurfacePackageToken, surfaceViewHostToken: IBinder, displayId: Int, width: Int, height: Int, executor: Executor, receiver: OutcomeReceiver<SurfaceControlViewHost.SurfacePackage!, Exception!>)

Requests a android.view.SurfaceControlViewHost.SurfacePackage to be inserted into a android.view.SurfaceView inside the calling app.

Public methods

execute

Added in API level 35
open fun execute(
    service: ComponentName,
    params: PersistableBundle,
    executor: Executor,
    receiver: OutcomeReceiver<OnDevicePersonalizationManager.ExecuteResult!, Exception!>
): Unit

Executes an IsolatedService in the OnDevicePersonalization sandbox. The platform binds to the specified IsolatedService in an isolated process and calls IsolatedWorker#onExecute(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 android.view.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<OnDevicePersonalizationManager.ExecuteResult!, Exception!>: 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 ExecuteResult#getOutputData() will return a non-null byte array. In case of an error, the receiver returns one of the following exceptions: Returns a android.content.pm.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

Added in API level 35
open fun requestSurfacePackage(
    surfacePackageToken: SurfacePackageToken,
    surfaceViewHostToken: IBinder,
    displayId: Int,
    width: Int,
    height: Int,
    executor: Executor,
    receiver: OutcomeReceiver<SurfaceControlViewHost.SurfacePackage!, Exception!>
): Unit

Requests a android.view.SurfaceControlViewHost.SurfacePackage to be inserted into a android.view.SurfaceView inside the calling app. The surface package will contain an android.view.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 android.view.SurfaceView, which is returned by android.view.SurfaceView#getHostToken() after the android.view.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 android.view.SurfaceControlViewHost.SurfacePackage, returned by Context.getDisplay().getDisplayId().
width Int: the width of the android.view.SurfaceControlViewHost.SurfacePackage in pixels.
height Int: the height of the android.view.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<SurfaceControlViewHost.SurfacePackage!, Exception!>: This either returns a android.view.SurfaceControlViewHost.SurfacePackage on success, or Exception on failure. The exception type is OnDevicePersonalizationException if execution of the handler fails. This value cannot be null.