When an impression occurs, Google Mobile Ads SDK calls the paid event handler with its associated revenue data. By implementing this handler, 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 LTV data capture in your iOS app.
Prerequisites
- Make sure you have turned on the impression-level ad revenue feature in the AdMob UI.
- Import Google Mobile Ads SDK 9.10.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:
Implement a paid event handler
Each ad format has a paidEventHandler
property of type GADPaidEventHandler
.
During the lifecycle of an ad event, Google Mobile Ads SDK monitors
impression events and invokes the handler with an earned value.
Swift
class
ViewController
:
UIViewController
,
FullScreenContentDelegate
{
var
rewardedAd
:
RewardedAd
?
func
requestRewardedAd
()
{
RewardedAd
.
load
(
with
:
" AD_UNIT_ID
"
,
request
:
Request
()
)
{
(
ad
,
error
)
in
if
let
error
=
error
{
print
(
"Rewarded ad failed to load with error:
\(
error
.
localizedDescription
)
"
)
return
}
if
let
ad
=
ad
{
self
.
rewardedAd
=
ad
self
.
rewardedAd
?.
paidEventHandler
=
{
adValue
in
// TODO: Send the impression-level ad revenue information to your preferred analytics
// server directly within this callback.
// Extract the impression-level ad revenue data.
let
value
=
adValue
.
value
let
precision
=
adValue
.
precision
let
currencyCode
=
adValue
.
currencyCode
// Get the ad unit ID.
let
adUnitId
=
ad
.
adUnitID
let
responseInfo
=
ad
.
responseInfo
let
loadedAdNetworkResponseInfo
=
responseInfo
?.
loadedAdNetworkResponseInfo
let
adSourceId
=
loadedAdNetworkResponseInfo
?.
adSourceID
let
adSourceInstanceId
=
loadedAdNetworkResponseInfo
?.
adSourceInstanceID
let
adSourceInstanceName
=
loadedAdNetworkResponseInfo
?.
adSourceInstanceName
let
adSourceName
=
loadedAdNetworkResponseInfo
?.
adSourceName
let
mediationGroupName
=
responseInfo
?.
extras
[
"mediation_group_name"
]
let
mediationABTestName
=
responseInfo
?.
extras
[
"mediation_ab_test_name"
]
let
mediationABTestVariant
=
responseInfo
?.
extras
[
"mediation_ab_test_variant"
]
}
}
}
}
}
Objective-C
@import
GoogleMobileAds
;
@import
UIKit
;
@interface
ViewController
()
@property
(
nonatomic
,
strong
)
GADRewardedAd
*
rewardedAd
;
@end
@implementation
ViewController
-
(
void
)
requestRewardedAd
{
__weak
ViewController
*
weakSelf
=
self
;
GADRequest
*
request
=
[
GADRequest
request
];
[
GADRewardedAd
loadWithAdUnitID
:
@" AD_UNIT_ID
"
request
:
request
completionHandler
:
^
(
GADRewardedAd
*
ad
,
NSError
*
error
)
{
if
(
error
)
{
NSLog
(
@"Rewarded ad failed to load with error: %@"
,
[
error
localizedDescription
]);
return
;
}
self
.
rewardedAd
=
ad
;
self
.
rewardedAd
.
paidEventHandler
=
^
void
(
GADAdValue
*
_Nonnull
value
){
ViewController
*
strongSelf
=
weakSelf
;
// TODO: Send the impression-level ad revenue information to your preferred analytics
// server directly within this callback.
// Extract the impression-level ad revenue data.
NSDecimalNumber
*
value
;
=
value
.
value
;
NSString
*
currencyCode
=
value
.
currencyCode
;
GADAdValuePrecision
precision
=
value
.
precision
;
// Get the ad unit ID.
NSString
*
adUnitId
=
strongSelf
.
rewardedAd
.
adUnitID
;
GADAdNetworkResponseInfo
*
loadedAdNetworkResponseInfo
=
strongSelf
.
rewardedAd
.
responseInfo
.
loadedAdNetworkResponseInfo
;
NSString
*
adSourceName
=
loadedAdNetworkResponseInfo
.
adSourceName
;
NSString
*
adSourceID
=
loadedAdNetworkResponseInfo
.
adSourceID
;
NSString
*
adSourceInstanceName
=
loadedAdNetworkResponseInfo
.
adSourceInstanceName
;
NSString
*
adSourceInstanceID
=
loadedAdNetworkResponseInfo
.
adSourceInstanceID
;
NSDictionary<
;
NSString
*
,
id>
;
*
extras
=
strongSelf
.
rewardedAd
.
responseInfo
.
extrasDictionary
;
NSString
*
mediationGroupName
=
extras
[
"mediation_group_name"
];
NSString
*
mediationABTestName
=
extras
[
"mediation_ab_test_name"
];
NSString
*
mediationABTestVariant
=
extras
[
"mediation_ab_test_variant"
];
};
]};
}
Identify a custom event ad source name
For custom event ad sources, adSourceName
property gives you 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 the following steps:
- Get the
adNetworkClassNameproperty. - Set a unique ad source name.
The following example sets a unique ad source name for a custom event:
Swift
func
uniqueAdSourceName
(
for
loadedAdNetworkResponseInfo
:
AdNetworkResponseInfo
)
-
>
String
{
var
adSourceName
:
String
=
loadedAdNetworkResponseInfo
.
adSourceName
??
""
if
adSourceName
==
"Custom Event"
{
if
loadedAdNetworkResponseInfo
.
adNetworkClassName
==
"MediationExample.SampleCustomEventSwift"
{
adSourceName
=
"Sample Ad Network (Custom Event)"
}
}
return
adSourceName
}
Objective-C
-
(
NSString
*
)
uniqueAdSourceNameForAdNetworkResponseInfo:
(
GADAdNetworkResponseInfo
*
)
loadedAdNetworkResponseInfo
{
NSString
*
adSourceName
=
loadedAdNetworkResponseInfo
.
adSourceName
;
if
([
adSourceName
isEqualToString
:
@"Custom Event"
])
{
if
([
loadedAdNetworkResponseInfo
.
adNetworkClassName
isEqualToString
:
@"SampleCustomEvent"
])
{
adSourceName
=
@"Sample Ad Network (Custom Event)"
;
}
}
return
adSourceName
;
}
For more information on the winning ad source, see Retrieve information about the ad response .
Integrate with App Attribution Partners (AAP)
For complete details on forwarding ads revenue data to analytics platforms, refer to the partner's guide:
| Partner SDK |
|---|
| Adjust |
| AppsFlyer |
| Singular |
| Tenjin |
Implementation best practices
- Set the handler 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 paid event information to your preferred analytics server
immediately at the time the
paidEventHandlermethod is called. This makes sure that you don't accidentally drop any callbacks and avoids data discrepancies.
GADAdValue
GADAdValue
is a class that represents the monetary value earned for an ad,
including the value's currency code and its precision type encoded as following.
| GADAdValuePrecision | Description |
|---|---|
GADAdValuePrecisionUnknown
|
An ad value that's unknown. This gets returned when LTV pingback is enabled but there isn't enough data available. |
GADAdValuePrecisionEstimated
|
An ad value estimated from aggregated data. |
GADAdValuePrecisionPublisherProvided
|
A publisher provided ad value, such as manual CPMs in a mediation group. |
GADAdValuePrecisionPrecise
|
The precise value paid for this ad. |
Test impressions from bidding ad sources
After an impression-level ad revenue event occurs for a bidding ad source through a test request, you receive only the following values:
-
GADAdValuePrecisionUnknown: indicates the precision type.
-
0: indicates the ad value.
Previously, you might have seen the precision type as a value other than GADAdValuePrecisionUnknown
and an ad value more than 0
.
For details on sending a test ad request, see Enable test devices .
