Handling Paid Events

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.