158 lines
8.4 KiB
Java
158 lines
8.4 KiB
Java
|
/*
|
||
|
|
* Copyright (C) 2023 The Android Open Source Project
|
||
|
|
*
|
||
|
|
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
|
|
* you may not use this file except in compliance with the License.
|
||
|
|
* You may obtain a copy of the License at
|
||
|
|
*
|
||
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
||
|
|
*
|
||
|
|
* Unless required by applicable law or agreed to in writing, software
|
||
|
|
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
|
|
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
|
|
* See the License for the specific language governing permissions and
|
||
|
|
* limitations under the License.
|
||
|
|
*/
|
||
|
|
|
||
|
|
package android.adservices.ondevicepersonalization;
|
||
|
|
|
||
|
|
import android.annotation.FlaggedApi;
|
||
|
|
import android.annotation.NonNull;
|
||
|
|
import android.os.OutcomeReceiver;
|
||
|
|
|
||
|
|
import com.android.adservices.ondevicepersonalization.flags.Flags;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Interface with methods that need to be implemented to handle requests from the
|
||
|
|
* OnDevicePersonalization service to an {@link IsolatedService}. The {@link IsolatedService}
|
||
|
|
* creates an instance of {@link IsolatedWorker} on each request and calls one of the methods
|
||
|
|
* below, depending the type of the request. The {@link IsolatedService} calls the method on a
|
||
|
|
* Binder thread and the {@link IsolatedWorker} should offload long running operations to a
|
||
|
|
* worker thread. The {@link IsolatedWorker} should use the {@code receiver} parameter of each
|
||
|
|
* method to return results. If any of these methods throws a {@link RuntimeException}, the
|
||
|
|
* platform treats it as an unrecoverable error in the {@link IsolatedService} and ends processing
|
||
|
|
* the request.
|
||
|
|
*/
|
||
|
|
@FlaggedApi(Flags.FLAG_ON_DEVICE_PERSONALIZATION_APIS_ENABLED)
|
||
|
|
public interface IsolatedWorker {
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Handles a request from an app. This method is called when an app calls {@code
|
||
|
|
* OnDevicePersonalizationManager#execute(ComponentName, PersistableBundle,
|
||
|
|
* java.util.concurrent.Executor, OutcomeReceiver)} that refers to a named
|
||
|
|
* {@link IsolatedService}.
|
||
|
|
*
|
||
|
|
* @param input Request Parameters from the calling app.
|
||
|
|
* @param receiver Callback that receives the result {@link ExecuteOutput} or an
|
||
|
|
* {@link IsolatedServiceException}. If this method throws a {@link RuntimeException} or
|
||
|
|
* returns either {@code null} or {@link IsolatedServiceException}, the error is indicated
|
||
|
|
* to the calling app as an {@link OnDevicePersonalizationException} with error code
|
||
|
|
* {@link 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 {@link IsolatedService} needs to report additional data beyond the error code to
|
||
|
|
* its backend servers, it should populate the logging fields in {@link ExecuteOutput} with
|
||
|
|
* the additional error data for logging, and rely on Federated Analytics for the stats.
|
||
|
|
*/
|
||
|
|
default void onExecute(
|
||
|
|
@NonNull ExecuteInput input,
|
||
|
|
@NonNull OutcomeReceiver<ExecuteOutput, IsolatedServiceException> receiver) {
|
||
|
|
receiver.onResult(new ExecuteOutput.Builder().build());
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Handles a completed download. The platform downloads content using the parameters defined in
|
||
|
|
* the package manifest of the {@link IsolatedService}, calls this function after the download
|
||
|
|
* is complete, and updates the REMOTE_DATA table from
|
||
|
|
* {@link IsolatedService#getRemoteData(RequestToken)} with the result of this method.
|
||
|
|
*
|
||
|
|
* @param input Download handler parameters.
|
||
|
|
* @param receiver Callback that receives the result {@link DownloadCompletedOutput} or an
|
||
|
|
* {@link IsolatedServiceException}.
|
||
|
|
* <p>If this method returns a {@code null} result or exception via the callback, or
|
||
|
|
* throws a {@link RuntimeException}, no updates are made to the REMOTE_DATA table.
|
||
|
|
*/
|
||
|
|
default void onDownloadCompleted(
|
||
|
|
@NonNull DownloadCompletedInput input,
|
||
|
|
@NonNull OutcomeReceiver<DownloadCompletedOutput, IsolatedServiceException> receiver) {
|
||
|
|
receiver.onResult(new DownloadCompletedOutput.Builder().build());
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Generates HTML for the results that were returned as a result of
|
||
|
|
* {@link #onExecute(ExecuteInput, android.os.OutcomeReceiver)}. Called when a client app calls
|
||
|
|
* {@link OnDevicePersonalizationManager#requestSurfacePackage(SurfacePackageToken, IBinder, int, int, int, java.util.concurrent.Executor, OutcomeReceiver)}.
|
||
|
|
* The platform will render this HTML in an {@link android.webkit.WebView} inside a fenced
|
||
|
|
* frame.
|
||
|
|
*
|
||
|
|
* @param input Parameters for the render request.
|
||
|
|
* @param receiver Callback that receives the result {@link RenderOutput} or an
|
||
|
|
* {@link IsolatedServiceException}.
|
||
|
|
* <p>If this method returns a {@code null} result or exception via the callback, or
|
||
|
|
* throws a {@link RuntimeException}, the error is also reported to calling
|
||
|
|
* apps as an {@link OnDevicePersonalizationException} with error code {@link
|
||
|
|
* OnDevicePersonalizationException#ERROR_ISOLATED_SERVICE_FAILED}.
|
||
|
|
*/
|
||
|
|
default void onRender(
|
||
|
|
@NonNull RenderInput input,
|
||
|
|
@NonNull OutcomeReceiver<RenderOutput, IsolatedServiceException> receiver) {
|
||
|
|
receiver.onResult(new RenderOutput.Builder().build());
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Handles an event triggered by a request to a platform-provided tracking URL {@link
|
||
|
|
* EventUrlProvider} that was embedded in the HTML output returned by
|
||
|
|
* {@link #onRender(RenderInput, android.os.OutcomeReceiver)}. The platform updates the EVENTS table with
|
||
|
|
* {@link EventOutput#getEventLogRecord()}.
|
||
|
|
*
|
||
|
|
* @param input The parameters needed to compute event data.
|
||
|
|
* @param receiver Callback that receives the result {@link EventOutput} or an
|
||
|
|
* {@link IsolatedServiceException}.
|
||
|
|
* <p>If this method returns a {@code null} result or exception via the callback, or
|
||
|
|
* throws a {@link RuntimeException}, no data is written to the EVENTS table.
|
||
|
|
*/
|
||
|
|
default void onEvent(
|
||
|
|
@NonNull EventInput input,
|
||
|
|
@NonNull OutcomeReceiver<EventOutput, IsolatedServiceException> receiver) {
|
||
|
|
receiver.onResult(new EventOutput.Builder().build());
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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 {@link FederatedComputeScheduler#schedule}.
|
||
|
|
*
|
||
|
|
* @param input The parameters needed to generate the training example.
|
||
|
|
* @param receiver Callback that receives the result {@link TrainingExamplesOutput} or an
|
||
|
|
* {@link IsolatedServiceException}.
|
||
|
|
* <p>If this method returns a {@code null} result or exception via the callback, or
|
||
|
|
* throws a {@link RuntimeException}, no training examples is produced for this
|
||
|
|
* training session.
|
||
|
|
*/
|
||
|
|
default void onTrainingExamples(
|
||
|
|
@NonNull TrainingExamplesInput input,
|
||
|
|
@NonNull OutcomeReceiver<TrainingExamplesOutput, IsolatedServiceException> receiver) {
|
||
|
|
receiver.onResult(new TrainingExamplesOutput.Builder().build());
|
||
|
|
}
|
||
|
|
|
||
|
|
/**
|
||
|
|
* 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 <a href="https://github.com/WICG/attribution-reporting-api">
|
||
|
|
* Attribution and Reporting API</a>. If the data in the web trigger payload indicates that the
|
||
|
|
* event should be forwarded to an {@link IsolatedService}, the platform will call this function
|
||
|
|
* with the web trigger data.
|
||
|
|
*
|
||
|
|
* @param input The parameters needed to process Web Trigger event.
|
||
|
|
* @param receiver Callback that receives the result {@link WebTriggerOutput} or an
|
||
|
|
* {@link IsolatedServiceException}. Should be called with a
|
||
|
|
* {@link WebTriggerOutput} object populated with a set of records to be written to the
|
||
|
|
* REQUESTS or EVENTS tables.
|
||
|
|
* <p>If this method returns a {@code null} result or exception via the callback, or
|
||
|
|
* throws a {@link RuntimeException}, no data is written to the REQUESTS orEVENTS tables.
|
||
|
|
*/
|
||
|
|
default void onWebTrigger(
|
||
|
|
@NonNull WebTriggerInput input,
|
||
|
|
@NonNull OutcomeReceiver<WebTriggerOutput, IsolatedServiceException> receiver) {
|
||
|
|
receiver.onResult(new WebTriggerOutput.Builder().build());
|
||
|
|
}
|
||
|
|
}
|