OnDevicePersonalizationManager

Kotlin |Java

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	`ExecuteResult` The result of a call to `OnDevicePersonalizationManager#execute(ComponentName,`

Public methods
open Unit	`execute(service: ComponentName, params: PersistableBundle, executor: Executor, receiver: OutcomeReceiver<OnDevicePersonalizationManager.ExecuteResult!, Exception!>)` 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 VanillaIceCream

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 the`IsolatedService`. 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 VanillaIceCream

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`.