When an impression occurs, Google Mobile Ads SDK (Legacy) provides ad revenue data associated with that impression. You can use the data to calculate a user's lifetime value, or forward the data downstream to other relevant systems. This guide is intended to help you implement the impression-level ad revenue data capture in your Android app. ## Prerequisites - Make sure you have [turned on the impression-level ad revenue feature](https://support.google.com/admanager/answer/13404416) in the Ad Manager UI. - Import Google Mobile Ads SDK (Legacy) 21.1.0 or higher. - [Set up Google Mobile Ads SDK (Legacy)](https://developers.google.com/ad-manager/mobile-ads-sdk/android/quick-start.md.txt). - Before you can receive any impression-level ad revenue, you need to implement at least one ad format: - [App open](https://developers.google.com/ad-manager/mobile-ads-sdk/android/app-open.md.txt) - [Banner](https://developers.google.com/ad-manager/mobile-ads-sdk/android/banner.md.txt) - [Interstitial](https://developers.google.com/ad-manager/mobile-ads-sdk/android/interstitial.md.txt) - [Rewarded](https://developers.google.com/ad-manager/mobile-ads-sdk/android/rewarded.md.txt) - [Rewarded interstitial](https://developers.google.com/ad-manager/mobile-ads-sdk/android/rewarded-interstitial.md.txt) - [Native](https://developers.google.com/ad-manager/mobile-ads-sdk/android/native.md.txt) ## Paid event handler Each ad format has an [`OnPaidEventListener`](https://developers.google.com/ad-manager/mobile-ads-sdk/android/reference/com/google/android/gms/ads/OnPaidEventListener.md.txt). During the lifecycle of an ad event, Google Mobile Ads SDK (Legacy) monitors impression events and invokes the handler with an earned value. The following example handles paid events for a rewarded ad: ### Java ```java private void setOnPaidEventListener(RewardedAd ad) { ad.setOnPaidEventListener( new OnPaidEventListener() { @Override public void onPaidEvent(@NonNull AdValue adValue) { // Extract the impression-level ad revenue data. long valueMicros = adValue.getValueMicros(); String currencyCode = adValue.getCurrencyCode(); int precision = adValue.getPrecisionType(); // Get the ad unit ID. String adUnitId = ad.getAdUnitId(); // Extract ad response information. AdapterResponseInfo loadedAdapterResponseInfo = ad.getResponseInfo().getLoadedAdapterResponseInfo(); if (loadedAdapterResponseInfo != null) { String adSourceName = loadedAdapterResponseInfo.getAdSourceName(); String adSourceId = loadedAdapterResponseInfo.getAdSourceId(); String adSourceInstanceName = loadedAdapterResponseInfo.getAdSourceInstanceName(); String adSourceInstanceId = loadedAdapterResponseInfo.getAdSourceInstanceId(); Bundle extras = ad.getResponseInfo().getResponseExtras(); String mediationGroupName = extras.getString("mediation_group_name"); String mediationABTestName = extras.getString("mediation_ab_test_name"); String mediationABTestVariant = extras.getString("mediation_ab_test_variant"); } } }); } ``` ### Kotlin ```kotlin private fun setOnPaidEventListener(ad: RewardedAd) { ad.onPaidEventListener = OnPaidEventListener { adValue -> // Extract the impression-level ad revenue data. val valueMicros = adValue.valueMicros val currencyCode = adValue.currencyCode val precision = adValue.precisionType // Get the ad unit ID. val adUnitId = ad.adUnitId // Extract ad response information. val loadedAdapterResponseInfo = ad.responseInfo.loadedAdapterResponseInfo val adSourceName = loadedAdapterResponseInfo?.adSourceName val adSourceId = loadedAdapterResponseInfo?.adSourceId val adSourceInstanceName = loadedAdapterResponseInfo?.adSourceInstanceName val adSourceInstanceId = loadedAdapterResponseInfo?.adSourceInstanceId val extras = ad.responseInfo.responseExtras val mediationGroupName = extras.getString("mediation_group_name") val mediationABTestName = extras.getString("mediation_ab_test_name") val mediationABTestVariant = extras.getString("mediation_ab_test_variant") } } ``` ### Identify a custom event ad source name For custom event ad sources, the [`getAdSourceName()`](https://developers.google.com/ad-manager/mobile-ads-sdk/android/reference/com/google/android/gms/ads/AdapterResponseInfo.md.txt#getAdSourceName()) method returns the ad source name `Custom event`. If you use multiple custom events, the ad source name isn't granular enough to distinguish between multiple custom events. To locate a specific custom event, do: 1. Call the [`getAdSourceName()`](https://developers.google.com/ad-manager/mobile-ads-sdk/android/reference/com/google/android/gms/ads/AdapterResponseInfo.md.txt#getAdSourceName()) method. 2. Set a unique ad source name. The following example sets a unique ad source name for a custom event: ### Java ```java private String getUniqueAdSourceName(@NonNull AdapterResponseInfo loadedAdapterResponseInfo) { String adSourceName = loadedAdapterResponseInfo.getAdSourceName(); if (adSourceName.equals("Custom Event")) { if (loadedAdapterResponseInfo .getAdapterClassName() .equals("com.google.ads.mediation.sample.customevent.SampleCustomEvent")) { adSourceName = "Sample Ad Network (Custom Event)"; } } return adSourceName; } ``` ### Kotlin ```kotlin private fun getUniqueAdSourceName(loadedAdapterResponseInfo: AdapterResponseInfo): String { var adSourceName = loadedAdapterResponseInfo.adSourceName if (adSourceName == "Custom Event") { if ( loadedAdapterResponseInfo.adapterClassName == "com.google.ads.mediation.sample.customevent.SampleCustomEvent" ) { adSourceName = "Sample Ad Network (Custom Event)" } } return adSourceName } ```
For more information on the winning ad source, see [Retrieve information about the ad response](https://developers.google.com/ad-manager/mobile-ads-sdk/android/response-info). ### Implementation best practices - Set the listener immediately once you create or get access to the ad object, and definitely before showing the ad. This makes sure that you don't miss any paid event callbacks. - Send the impression-level ad revenue information to your preferred analytics server immediately at the time the paid event callback is called. This makes sure that you don't accidentally drop any callbacks and avoids data discrepancies. ## AdValue `AdValue` is a class that represents the monetary value earned for an ad, including the value's currency code and its precision type encoded as follows. > [!IMPORTANT] > **Key Point:** [`getValueMicros()`](https://developers.google.com/ad-manager/mobile-ads-sdk/android/reference/com/google/android/gms/ads/AdValue.md.txt#public-long-getvaluemicros) returns the value of the ad in micro units. For example, a `getValueMicros()` returned value of 5,000 means the ad is estimated to be worth $0.005. | PrecisionType | Description | |---|---| | `UNKNOWN` | An ad value that's unknown. This gets returned when LTV pingback is enabled but there isn't enough data available. | | `ESTIMATED` | An ad value estimated from aggregated data. | | `PUBLISHER_PROVIDED` | A publisher provided ad value, such as manual CPMs in a mediation group. | | `PRECISE` | The precise value paid for this ad. | In the case of mediation, Ad Manager tries to provide an `ESTIMATED` value for ad sources that have [automatic data collection](https://support.google.com/admanager/answer/6240051) enabled. For non-optimized ad sources, or in cases where there aren't enough aggregated data to report a meaningful estimation, the `PUBLISHER_PROVIDED` value is returned. ### Test impressions from Open Bidding After an impression-level ad revenue event occurs for an Open Bidding ad source through a test request, you receive only the following values: - `UNKNOWN`: indicates the precision type. - `0`: indicates the ad value. Previously, you might have seen the precision type as a value other than `UNKNOWN` and an ad value more than `0`. For details on sending a test ad request, see [Enable test devices](https://developers.google.com/ad-manager/mobile-ads-sdk/android/test-ads.md.txt#enable-test-devices).