AdSelectionManager.ReportImpression Method

Definition

Namespace:

Android.AdServices.AdSelection

Assembly:

Mono.Android.dll

Notifies the service that there is a new impression to report for the ad selected by the ad-selection run identified by adSelectionId.

[Android.Runtime.Register("reportImpression", "(Landroid/adservices/adselection/ReportImpressionRequest;Ljava/util/concurrent/Executor;Landroid/os/OutcomeReceiver;)V", "GetReportImpression_Landroid_adservices_adselection_ReportImpressionRequest_Ljava_util_concurrent_Executor_Landroid_os_OutcomeReceiver_Handler", ApiSince=34)]
public virtual void ReportImpression (Android.AdServices.AdSelection.ReportImpressionRequest request, Java.Util.Concurrent.IExecutor executor, Android.OS.IOutcomeReceiver receiver);

[<Android.Runtime.Register("reportImpression", "(Landroid/adservices/adselection/ReportImpressionRequest;Ljava/util/concurrent/Executor;Landroid/os/OutcomeReceiver;)V", "GetReportImpression_Landroid_adservices_adselection_ReportImpressionRequest_Ljava_util_concurrent_Executor_Landroid_os_OutcomeReceiver_Handler", ApiSince=34)>]
abstract member ReportImpression : Android.AdServices.AdSelection.ReportImpressionRequest * Java.Util.Concurrent.IExecutor * Android.OS.IOutcomeReceiver -> unit
override this.ReportImpression : Android.AdServices.AdSelection.ReportImpressionRequest * Java.Util.Concurrent.IExecutor * Android.OS.IOutcomeReceiver -> unit

Parameters

request

ReportImpressionRequest

executor

IExecutor

receiver

IOutcomeReceiver

Attributes

RegisterAttribute

Remarks

Notifies the service that there is a new impression to report for the ad selected by the ad-selection run identified by adSelectionId. There is no guarantee about when the impression will be reported. The impression reporting could be delayed and reports could be batched.

To calculate the winning seller reporting URL, the service fetches the seller's JavaScript logic from the AdSelectionConfig#getDecisionLogicUri() found at ReportImpressionRequest#getAdSelectionConfig(). Then, the service executes one of the functions found in the seller JS called reportResult, providing on-device signals as well as ReportImpressionRequest#getAdSelectionConfig() as input parameters.

The function definition of reportResult is:

function reportResult(ad_selection_config, render_url, bid, contextual_signals) { return { 'status': status, 'results': {'signals_for_buyer': signals_for_buyer, 'reporting_url': reporting_url}; }}

To calculate the winning buyer reporting URL, the service fetches the winning buyer's JavaScript logic which is fetched via the buyer's android.adservices.customaudience.CustomAudience#getBiddingLogicUri(). Then, the service executes one of the functions found in the buyer JS called reportWin, providing on-device signals, signals_for_buyer calculated by reportResult, and specific fields from ReportImpressionRequest#getAdSelectionConfig() as input parameters.

The function definition of reportWin is:

function reportWin(ad_selection_signals, per_buyer_signals, signals_for_buyer, contextual_signals, custom_audience_reporting_signals) { return {'status': 0, 'results': {'reporting_url': reporting_url}; }}

In addition, buyers and sellers have the option to register to receive reports on specific ad events. To do so, they can invoke the platform provided registerAdBeacon function inside reportWin and reportResult for buyers and sellers, respectively.

The function definition of registerBeacon is:

function registerAdBeacon(beacons), where beacons is a dict of string to string pairs

For each ad event a buyer/seller is interested in reports for, they would add an event_key: event_reporting_uri pair to the beacons dict, where event_key is an identifier for that specific event. This event_key should match ReportEventRequest#getKey() when the SDK invokes #reportEvent. In addition, each event_reporting_uri should parse properly into a android.net.Uri. This will be the android.net.Uri reported to when the SDK invokes #reportEvent.

When the buyer/seller has added all the pairings they want to receive events for, they can invoke registerAdBeacon(beacons), where beacons is the name of the dict they added the pairs to.

registerAdBeacon will throw a TypeError in these situations:

<ol> <li>registerAdBeaconis called more than once. If this error is caught in reportWin/reportResult, the original set of pairings will be registered <li>registerAdBeacon doesn't have exactly 1 dict argument. <li>The contents of the 1 dict argument are not all String: String pairings. </ol>

The output is passed by the receiver, which either returns an empty Object for a successful run, or an Exception includes the type of the exception thrown and the corresponding error message.

If the IllegalArgumentException is thrown, it is caused by invalid input argument the API received to report the impression.

If the IllegalStateException is thrown with error message "Failure of AdSelection services.", it is caused by an internal failure of the ad selection service.

If the LimitExceededException is thrown, it is caused when the calling package exceeds the allowed rate limits and is throttled.

If the SecurityException is thrown, it is caused when the caller is not authorized or permission is not requested.

Impressions will be reported at most once as a best-effort attempt.

Java documentation for android.adservices.adselection.AdSelectionManager.reportImpression(android.adservices.adselection.ReportImpressionRequest, java.util.concurrent.Executor, android.os.OutcomeReceiver<java.lang.Object, java.lang.Exception>).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.