IsolatedService

public abstract class IsolatedService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.adservices.ondevicepersonalization.IsolatedService


Base class for services that are started by ODP on a call to OnDevicePersonalizationManager#execute(ComponentName, PersistableBundle, java.util.concurrent.Executor, OutcomeReceiver) and run in an isolated process. The service can produce content to be displayed in a SurfaceView in a calling app and 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. Client apps use OnDevicePersonalizationManager to interact with an IsolatedService.

Summary

Inherited constants

Public constructors

IsolatedService()

Public methods

final EventUrlProvider getEventUrlProvider(RequestToken requestToken)

Returns an EventUrlProvider for the current request.

final FederatedComputeScheduler getFederatedComputeScheduler(RequestToken requestToken)

Returns an FederatedComputeScheduler for the current request.

final MutableKeyValueStore getLocalData(RequestToken requestToken)

Returns a Data Access Object for the LOCAL_DATA table.

final LogReader getLogReader(RequestToken requestToken)

Returns a DAO for the REQUESTS and EVENTS tables that provides access to the rows that are readable by the IsolatedService.

final KeyValueStore getRemoteData(RequestToken requestToken)

Returns a Data Access Object for the REMOTE_DATA table.

final UserData getUserData(RequestToken requestToken)

Returns the platform-provided UserData for the current request.

IBinder onBind(Intent intent)

Handles binding to the IsolatedService.

void onCreate()

Creates a binder for an IsolatedService.

abstract IsolatedWorker onRequest(RequestToken requestToken)

Return an instance of an IsolatedWorker that handles client requests.

Inherited methods

Public constructors

IsolatedService

public IsolatedService ()

Public methods

getEventUrlProvider

public final EventUrlProvider getEventUrlProvider (RequestToken requestToken)

Returns an EventUrlProvider for the current request. The EventUrlProvider provides URLs that can be embedded in HTML. When the HTML is rendered in an WebView, the platform intercepts requests to these URLs and invokes IsolatedWorker#onEvent(EventInput, Consumer).

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service. This value cannot be null.

Returns
EventUrlProvider An EventUrlProvider that returns event tracking URLs. This value cannot be null.

getFederatedComputeScheduler

public final FederatedComputeScheduler getFederatedComputeScheduler (RequestToken requestToken)

Returns an FederatedComputeScheduler for the current request. The FederatedComputeScheduler can be used to schedule and cancel federated computation jobs. The federated computation includes federated learning and federated analytic jobs.

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service. This value cannot be null.

Returns
FederatedComputeScheduler An FederatedComputeScheduler that returns a federated computation job scheduler. This value cannot be null.

getLocalData

public final MutableKeyValueStore getLocalData (RequestToken requestToken)

Returns a Data Access Object for the LOCAL_DATA table. The LOCAL_DATA table is a persistent key-value store that the service can use to store any data. The contents of this table are visible only to the service running in an isolated process and cannot be sent outside the device.

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service. This value cannot be null.

Returns
MutableKeyValueStore A MutableKeyValueStore object that provides access to the LOCAL_DATA table. The methods in the returned MutableKeyValueStore are blocking operations and should be called from a worker thread and not the main thread or a binder thread. This value cannot be null.

getLogReader

public final LogReader getLogReader (RequestToken requestToken)

Returns a DAO for the REQUESTS and EVENTS tables that provides access to the rows that are readable by the IsolatedService.

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service. This value cannot be null.

Returns
LogReader A LogReader object that provides access to the REQUESTS and EVENTS table. The methods in the returned LogReader are blocking operations and should be called from a worker thread and not the main thread or a binder thread. This value cannot be null.

getRemoteData

public final KeyValueStore getRemoteData (RequestToken requestToken)

Returns a Data Access Object for the REMOTE_DATA table. The REMOTE_DATA table is a read-only key-value store that contains data that is periodically downloaded from an endpoint declared in the tag in the ODP manifest of the service, as shown in the following example.

<!-- Contents of res/xml/OdpSettings.xml -->
 <on-device-personalization>
 <!-- Name of the service subclass -->
 <service "com.example.odpsample.SampleService">
   <!-- If this tag is present, ODP will periodically poll this URL and
    download content to populate REMOTE_DATA. Adopters that do not need to
    download content from their servers can skip this tag. -->
   <download-settings url="https://example.com/get" />
 </service>
 </on-device-personalization>
 

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service. This value cannot be null.

Returns
KeyValueStore A KeyValueStore object that provides access to the REMOTE_DATA table. The methods in the returned KeyValueStore are blocking operations and should be called from a worker thread and not the main thread or a binder thread. This value cannot be null.

getUserData

public final UserData getUserData (RequestToken requestToken)

Returns the platform-provided UserData for the current request.

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service. This value cannot be null.

Returns
UserData A UserData object. This value may be null.

onBind

public IBinder onBind (Intent intent)

Handles binding to the IsolatedService.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here. This value cannot be null.

Returns
IBinder This value may be null.

onCreate

public void onCreate ()

Creates a binder for an IsolatedService.

onRequest

public abstract IsolatedWorker onRequest (RequestToken requestToken)

Return an instance of an IsolatedWorker that handles client requests.

Parameters
requestToken RequestToken: an opaque token that identifies the current request to the service that must be passed to service methods that depend on per-request state. This value cannot be null.

Returns
IsolatedWorker This value cannot be null.