When a paid event occurs, the Google Mobile Ads SDK calls a handler of the event with its associated revenue data. By implementing this handler, you can use the data to calculate a user's long term value, or forward the data downstream to other relevant systems.
This guide is intended to help you implement paid event data capture in your iOS app.
Prerequisites
- Reach out to your account manager to get allowlisted for this feature.
- Import the Google Mobile Ads SDK 7.54.0 or higher, either by itself or as part of Firebase.
- Before you can receive any paid event, you need to implement at least one ad format:
Implementing paid event handler
Each ad format has a paidEventHandler
property of type
GADPaidEventHandler
.
During the lifecycle of an ad event, the Google Mobile Ads SDK monitors paid
events and invokes the handler with an earned value. You set this handler after
initializing an ad and before showing it. The code below demonstrates how to
handle paid events for rewarded ads:
- (void)requestRewardedAd { self.rewardedAd = [[GADRewardedAd alloc] initWithAdUnitID:@"ad unit ID"]; __weak ViewController *weakSelf = self; self.rewardedAd.paidEventHandler = ^void(GADAdValue *_Nonnull value){ ViewController *strongSelf = weakSelf; NSLog(@"Paid event of value %@ in currency %@ occurred for ad unit %@ from ad network adapter %@).", value.value, value.currencyCode, strongSelf.rewardedAd.adUnitID, strongSelf.rewardedAd.responseInfo.adNetworkClassName); }; [self.rewardedAd loadRequest:[GADRequest request] completionHandler:^(GADRequestError *_Nullable error) { ... }]; }
Some formats such as native ads don't provide access to the ad object until the
ad loads. In this case, the handler should be set at ad load time. Here is an
example for native ads, using the adLoader:didReceiveUnifiedNativeAd:
delegate method.
- (void)adLoader:(GADAdLoader *)adLoader didReceiveUnifiedNativeAd:(GADUnifiedNativeAd *)nativeAd {
nativeAd.paidEventHandler = ^void(GADAdValue *_Nonnull value){
NSLog(@"Paid event of value %@ in currency %@ occurred for ad %@).",
value.value, value.currencyCode, adLoader.adUnitID);
};
}
GADAdValue
GADAdValue
is a class that represents the value earned per paid event,
including the value's currency code and its precision type encoded as below.
GADAdValuePrecision | Description |
---|---|
GADAdValuePrecisionUnknown
|
An ad value with unknown precision. This is a placeholder value; in practice, all paid events should have a real precision. |
GADAdValuePrecisionEstimated
|
An ad value estimated from 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. |