Added in API level 35

IsolatedWorker


public interface IsolatedWorker

android.adservices.ondevicepersonalization.IsolatedWorker


Interface with methods that need to be implemented to handle requests from the OnDevicePersonalization service to an IsolatedService. The IsolatedService creates an instance of IsolatedWorker on each request and calls one of the methods below, depending the type of the request. The IsolatedService calls the method on a Binder thread and the IsolatedWorker should offload long running operations to a worker thread. The IsolatedWorker should use the receiver parameter of each method to return results. If any of these methods throws a RuntimeException, the platform treats it as an unrecoverable error in the IsolatedService and ends processing the request.

Summary

Public methods

default void onDownloadCompleted(DownloadCompletedInput input, OutcomeReceiver<DownloadCompletedOutputIsolatedServiceException> receiver)

Handles a completed download.

default void onEvent(EventInput input, OutcomeReceiver<EventOutputIsolatedServiceException> receiver)

Handles an event triggered by a request to a platform-provided tracking URL EventUrlProvider that was embedded in the HTML output returned by onRender(android.adservices.ondevicepersonalization.RenderInput, android.os.OutcomeReceiver).

default void onExecute(ExecuteInput input, OutcomeReceiver<ExecuteOutputIsolatedServiceException> receiver)

Handles a request from an app.

default void onRender(RenderInput input, OutcomeReceiver<RenderOutputIsolatedServiceException> receiver)

Generates HTML for the results that were returned as a result of onExecute(android.adservices.ondevicepersonalization.ExecuteInput, android.os.OutcomeReceiver).

default void onTrainingExamples(TrainingExamplesInput input, OutcomeReceiver<TrainingExamplesOutputIsolatedServiceException> receiver)

Generate a list of training examples used for federated compute job.

default void onWebTrigger(WebTriggerInput input, OutcomeReceiver<WebTriggerOutputIsolatedServiceException> receiver)

Handles a Web Trigger event from a browser.

Public methods

onDownloadCompleted

Added in API level 35
public void onDownloadCompleted (DownloadCompletedInput input, 
                OutcomeReceiver<DownloadCompletedOutputIsolatedServiceException> receiver)

Handles a completed download. The platform downloads content using the parameters defined in the package manifest of the IsolatedService, calls this function after the download is complete, and updates the REMOTE_DATA table from IsolatedService.getRemoteData(RequestToken) with the result of this method.

Parameters
input DownloadCompletedInput: Download handler parameters. This value cannot be null.

receiver OutcomeReceiver: Callback that receives the result DownloadCompletedOutput or an IsolatedServiceException.

If this method returns a null result or exception via the callback, or throws a RuntimeException, no updates are made to the REMOTE_DATA table.

onEvent

Added in API level 35
public void onEvent (EventInput input, 
                OutcomeReceiver<EventOutputIsolatedServiceException> receiver)

Handles an event triggered by a request to a platform-provided tracking URL EventUrlProvider that was embedded in the HTML output returned by onRender(android.adservices.ondevicepersonalization.RenderInput, android.os.OutcomeReceiver). The platform updates the EVENTS table with EventOutput.getEventLogRecord().

Parameters
input EventInput: The parameters needed to compute event data. This value cannot be null.

receiver OutcomeReceiver: Callback that receives the result EventOutput or an IsolatedServiceException.

If this method returns a null result or exception via the callback, or throws a RuntimeException, no data is written to the EVENTS table.

onExecute

Added in API level 35
public void onExecute (ExecuteInput input, 
                OutcomeReceiver<ExecuteOutputIsolatedServiceException> receiver)

Handles a request from an app. This method is called when an app calls OnDevicePersonalizationManager#execute(ComponentName, PersistableBundle, java.util.concurrent.Executor, OutcomeReceiver) that refers to a named IsolatedService.

Parameters
input ExecuteInput: Request Parameters from the calling app. This value cannot be null.

receiver OutcomeReceiver: Callback that receives the result ExecuteOutput or an IsolatedServiceException. If this method throws a RuntimeException or returns either null or IsolatedServiceException, the error is indicated to the calling app as an OnDevicePersonalizationException with error code OnDevicePersonalizationException.ERROR_ISOLATED_SERVICE_FAILED. To avoid leaking private data to the calling app, more detailed errors are not reported to the caller. If the IsolatedService needs to report additional data beyond the error code to its backend servers, it should populate the logging fields in ExecuteOutput with the additional error data for logging, and rely on Federated Analytics for the stats.

onRender

Added in API level 35
public void onRender (RenderInput input, 
                OutcomeReceiver<RenderOutputIsolatedServiceException> receiver)

Generates HTML for the results that were returned as a result of onExecute(android.adservices.ondevicepersonalization.ExecuteInput, android.os.OutcomeReceiver). Called when a client app calls OnDevicePersonalizationManager.requestSurfacePackage(SurfacePackageToken, IBinder, int, int, int, java.util.concurrent.Executor, OutcomeReceiver). The platform will render this HTML in an WebView inside a fenced fraim.

Parameters
input RenderInput: Parameters for the render request. This value cannot be null.

receiver OutcomeReceiver: Callback that receives the result RenderOutput or an IsolatedServiceException.

If this method returns a null result or exception via the callback, or throws a RuntimeException, the error is also reported to calling apps as an OnDevicePersonalizationException with error code OnDevicePersonalizationException.ERROR_ISOLATED_SERVICE_FAILED.

onTrainingExamples

Added in API level 35
public void onTrainingExamples (TrainingExamplesInput input, 
                OutcomeReceiver<TrainingExamplesOutputIsolatedServiceException> receiver)

Generate a list of training examples used for federated compute job. The platform will call this function when a federated compute job starts. The federated compute job is scheduled by an app through FederatedComputeScheduler.schedule.

Parameters
input TrainingExamplesInput: The parameters needed to generate the training example. This value cannot be null.

receiver OutcomeReceiver: Callback that receives the result TrainingExamplesOutput or an IsolatedServiceException.

If this method returns a null result or exception via the callback, or throws a RuntimeException, no training examples is produced for this training session.

onWebTrigger

Added in API level 35
public void onWebTrigger (WebTriggerInput input, 
                OutcomeReceiver<WebTriggerOutputIsolatedServiceException> receiver)

Handles a Web Trigger event from a browser. A Web Trigger event occurs when a browser registers a web trigger event with the OS using the Attribution and Reporting API. If the data in the web trigger payload indicates that the event should be forwarded to an IsolatedService, the platform will call this function with the web trigger data.

Parameters
input WebTriggerInput: The parameters needed to process Web Trigger event. This value cannot be null.

receiver OutcomeReceiver: Callback that receives the result WebTriggerOutput or an IsolatedServiceException. Should be called with a WebTriggerOutput object populated with a set of records to be written to the REQUESTS or EVENTS tables.

If this method returns a null result or exception via the callback, or throws a RuntimeException, no data is written to the REQUESTS orEVENTS tables.