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

Constants
static Int	`FEATURE_DISABLED` Indicates that a feature is present but disabled on the device.
static Int	`FEATURE_ENABLED` Indicates that a feature is present and enabled on the device.
static Int	`FEATURE_UNSUPPORTED` Indicates that a feature is not supported on the device.

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	`executeInIsolatedService(request: ExecuteInIsolatedServiceRequest, executor: Executor, receiver: OutcomeReceiver<ExecuteInIsolatedServiceResponse!, Exception!>)` Executes an `IsolatedService` in the OnDevicePersonalization sandbox.
open Unit	`queryFeatureAvailability(featureName: String, executor: Executor, receiver: OutcomeReceiver<Int!, Exception!>)` Get the status of a specific OnDevicePersonalization feature.
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.

Constants

FEATURE_DISABLED

Added in API level 36.1

static val FEATURE_DISABLED: Int

Indicates that a feature is present but disabled on the device.

Value: 1

FEATURE_ENABLED

Added in API level 36.1

static val FEATURE_ENABLED: Int

Indicates that a feature is present and enabled on the device.

Value: 0

FEATURE_UNSUPPORTED

Added in API level 36.1

static val FEATURE_UNSUPPORTED: Int

Indicates that a feature is not supported on the device.

Value: 2

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 android.adservices.ondevicepersonalization.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 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 `android.adservices.ondevicepersonalization.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 `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.

executeInIsolatedService

Added in API level 36

open fun executeInIsolatedService(
    request: ExecuteInIsolatedServiceRequest, 
    executor: Executor, 
    receiver: OutcomeReceiver<ExecuteInIsolatedServiceResponse!, Exception!>
): Unit

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<ExecuteInIsolatedServiceResponse!, Exception!>: 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`.

queryFeatureAvailability

Added in API level 36.1

open fun queryFeatureAvailability(
    featureName: String, 
    executor: Executor, 
    receiver: OutcomeReceiver<Int!, Exception!>
): Unit

Get the status of a specific OnDevicePersonalization feature.

Parameters
`featureName`	String: the name of the specific feature to check the availability of. 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<Int!, Exception!>: this either returns a value of `FeatureStatus` on success or `Exception` on failure. The exception type is `IllegalStateException` if the service is not available. This value cannot be `null`.

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