Page Summary
-
Impression-level ad revenue data is provided by the Google Mobile Ads SDK when an impression occurs and can be used to calculate user lifetime value or forwarded to other systems.
-
Implementing impression-level ad revenue data capture in your Android app requires turning on the feature in Ad Manager, importing Google Mobile Ads SDK 21.1.0 or higher, completing the Get started guide, and implementing at least one ad format.
-
The
OnPaidEventListenerfor each ad format is invoked by the Google Mobile Ads SDK with an earned value when an impression event is monitored. -
AdValuerepresents the monetary value earned for an ad, including its currency code and precision type. -
You should set the
OnPaidEventListenerimmediately once you have access to the ad object and send the impression-level ad revenue information to your analytics server promptly to avoid data discrepancies.
When an impression occurs, Google Mobile Ads SDK 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 in the Ad Manager UI.
- Import Google Mobile Ads SDK 21.1.0 or higher.
- Complete the Get started guide .
-
Before you can receive any impression-level ad revenue, you need to implement at least one ad format:
Paid event handler
Each ad format has an OnPaidEventListener
.
During the lifecycle of an ad event, Google Mobile Ads SDK
monitors
impression events and invokes the handler with an earned value.
The following example handles paid events for a rewarded ad:
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
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()
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:
- Call the
getAdSourceName()method. - Set a unique ad source name.
The following example sets a unique ad source name for a custom event:
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
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 .
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.
| 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
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 .
