Impression-level ad revenue

Stay organized with collections Save and categorize content based on your preferences.

When an impression occurs, the 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

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 impression events and invokes the handler with an earned value.

@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 *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"];
    };
  ]};
}

Integrating 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 ensures you don't miss any paid event callbacks.
  • Send the paid event information to your preferred analytics server immediately at the time the paidEventHandler method is called. This ensures 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 below.

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.

Winning ad source information

When logging impression-level ad revenue, you can get more information about the winning ad source from the loadedAdNetworkResponseInfo property in GADResponseInfo.

[GADRewardedAd
  loadWithAdUnitID:@"ad unit ID"
  request:[GADRequest 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;

    GADAdNetworkResponseInfo *loadedAdNetworkResponseInfo =
        strongSelf.rewardedAd.responseInfo.loadedAdNetworkResponseInfo;
    NSString *adSourceName = loadedAdNetworkResponseInfo.adSourceName;
    NSString *adSourceID = loadedAdNetworkResponseInfo.adSourceID;
    NSString *adSourceInstanceName = loadedAdNetworkResponseInfo.adSourceInstanceName;
    NSString *adSourceInstanceID = loadedAdNetworkResponseInfo.adSourceInstanceID;
  };
]

Additional ad metadata

Additional ad metadata might be available through extrasDictionary. For example, if you're using mediation, the mediation group name of the winning ad is available through the mediation_group_name key.

[GADRewardedAd
  loadWithAdUnitID:@"ad unit ID"
  request:[GADRequest 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;

    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"];
  };
]