Integrate Impression-Level Revenue Data

Use this document to start ingesting Impression-Level Revenue Data (ILRD).

Before you start this section:

  1. Make sure you are on MoPub SDK v5.7.0 or above.
  2. Read the article explaining Impression-Level Revenue Data (ILRD) to understand the flow of events that you will be implementing below.

There are two approaches to receive Impression data, one is register to NSNotificationCenter to receive impression data and the other approach is to set the impression callback delegate which is the most convinient way for publishers to receive callback for every impression.

Register to NSNotificationCenter

  1. Publishers and third party SDKs can now subscribe to the events from NSNotificationCenter to get notified of impressions and receive detailed impression data.
  2. Call addObserver with notification name constant kMPImpressionTrackedNotification (Swift: NSNotification.Name.mpImpressionTracked) to receive impression events.
  3. Call removeObserver to unsubscribe from impression-level revenue data events.
  4. The MPImpressionData object, if included in the notification, is available in the notification object’s userInfo dictionary under key kMPImpressionTrackedInfoImpressionDataKey. More information can be found in the MPImpressionTrackedNotification.h header file in the SDK.

Example

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    // ...
    
    [[NSNotificationCenter defaultCenter] addObserver:self
                                             selector:@selector(onImpressionTracked:)
                                                 name:kMPImpressionTrackedNotification
                                               object:nil];

    // ...
    
    return YES;
}

- (void)onImpressionTracked:(NSNotification *)notification {
    id<MPMoPubAd> adObject = notification.object; // nil for Rewarded Video, otherwise your MPAdView/MPInterstitialAdController/MPNativeAd
    NSString * adUnitID = notification.userInfo[kMPImpressionTrackedInfoAdUnitIDKey]; // always filled with the adunit ID
    MPImpressionData * impressionData = notification.userInfo[kMPImpressionTrackedInfoImpressionDataKey]; // the impression's impression data, or nil if ILRD is not enabled
}

- (void)dealloc {
    [[NSNotificationCenter defaultCenter] removeObserver:self];
}
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // ...

    NotificationCenter.default.addObserver(self,
                                           selector: #selector(AppDelegate.onImpressionFiredNotification(notification:)),
                                           name: NSNotification.Name.mpImpressionTracked,
                                           object: nil)

    // ...

    return true
}

deinit {
    NotificationCenter.default.removeObserver(self)
}

@objc
func onImpressionFiredNotification(notification: NSNotification) {
    guard let userInfo = notification.userInfo as? [String: Any] else {
        return
    }
    
    let adObject: MPMoPubAd? = notification.object as? MPMoPubAd // nil for Rewarded Video, otherwise your MPAdView/MPInterstitialAdController/MPNativeAd
    let adUnitID: String = userInfo[kMPImpressionTrackedInfoAdUnitIDKey] as! String // always filled with the adunit ID
    let impressionData: MPImpressionData? = userInfo[kMPImpressionTrackedInfoImpressionDataKey] as? MPImpressionData // the impression's impression data, or nil if ILRD is not enabled
}

Set the Impression Callback Delegate

We have provided an additional delegate (callback) to listen to impression events when an ad is shown. A unified ad delegate is used by all formats except for rewarded video, which uses MPRewardedVideoDelegate.

MPMoPubAdDelegate is overridden by the other delegate protocols, so you access the callback by implementing MPAdViewDelegate (for banners), MPInterstitialAdControllerDelegate (for interstitials), and MPNativeAdDelegate (for static native), and setting the corresponding delegate object(s).

Set the ad’s delegate object and implement one of the below methods to receive ad events.

  • For rewarded videos, use didTrackImpressionWithAdUnitID:impressionData:
  • For all other ad formats, use mopubAd:didTrackImpressionWithImpressionData:

Note that impression data will be nil unless you have enabled this feature with your MoPub account representative.

Rewarded Video Ads

MPRewardedVideoDelegate includes a variety of optional callbacks that you can use to be notified of events; for example, when a rewarded video has successfully loaded, or when a rewarded video impression is fired. Check out the MPRewardedVideoDelegate for the following impression callback method:

/**
 Called when an impression is fired on a Rewarded Video. Includes information about the impression, if applicable.
 
 @param adUnitID The ad unit ID of the rewarded video that fired the impression.
 @param impressionData Information about the impression, or @c nil if the server didn't return any information.
 */
- (void)didTrackImpressionWithAdUnitID:(NSString *)adUnitID impressionData:(MPImpressionData *)impressionData;

Example

- (void)didTrackImpressionWithAdUnitID:(NSString *)adUnitID impressionData:(MPImpressionData * _Nullable)impressionData
{
	   // MPImpressionData has direct getters to individual properties
	   NSLog(@"adUnitID: %@" impressionData.adUnitID); // to access adunit ID
	   NSLog(@"adUnitFormat: %@" impressionData.adUnitFormat); // to access ad format

    // impressionData
    if (impressionData == nil)
    {
        return;
    }
    
    // impressionObject
    NSError *jsonSerializationError = nil;
    NSObject *impressionObject = [NSJSONSerialization JSONObjectWithData:impressionData.jsonRepresentation options:0 error:&jsonSerializationError];
    
    // impressionDictionary
    NSDictionary *impressionDictionary = [impressionObject isKindOfClass:NSDictionary.class] ? (NSDictionary *)impressionObject : nil;
    if (impressionDictionary == nil)
    {
        return;
    }
}

MPMoPubAdDelegate includes impression callback that you can use to be notified of impression events. Check out MPMoPubAdDelegate for the following impression callback method:

@optional
/**
 Called when an impression is fired on the @c MPMoPubAd instance. Includes information about the impression if applicable.
 
 @param ad The @c MPMoPubAd instance that fired the impression
 @param impressionData Information about the impression, or @c nil if the server didn't return any information.
 */
- (void)mopubAd:(id<MPMoPubAd>)ad didTrackImpressionWithImpressionData:(MPImpressionData * _Nullable)impressionData;

Example

- (void)mopubAd:(id<MPMoPubAd>)ad didTrackImpressionWithImpressionData:(MPImpressionData * _Nullable)impressionData
{
    // impressionData
    if (impressionData == nil)
    {
        return;
    }
    
    // impressionObject
    NSError *jsonSerializationError = nil;
    NSObject *impressionObject = [NSJSONSerialization JSONObjectWithData:impressionData.jsonRepresentation options:0 error:&jsonSerializationError];
 
    // impressionDictionary
    NSDictionary *impressionDictionary = [impressionObject isKindOfClass:NSDictionary.class] ? (NSDictionary *)impressionObject : nil;
    if (impressionDictionary == nil)
    {
        return;
    }
    
}

Native Ads

MPMoPubAdPlacerDelegate and MPNativeAdDelegate includes impression callbacks that you can use to track impression events. Check out MPMoPubAdPlacerDelegate and MPNativeAdDelegate for the following impression callback methods:

/**
 Called when an impression is fired on the @c MPMoPubAdPlacer instance. Includes
 information about the impression if applicable.
 
 @param adPlacer The @c MPMoPubAdPlacer instance that fired the impression
 @param ad The @c MPMoPubAd instance that fired the impression
 @param impressionData Information about the impression, or @c nil if the server didn't return any information.
 */

// for Adplacer ads
- (void)mopubAdPlacer:(id<MPMoPubAdPlacer>)adPlacer didTrackImpressionForAd:(id<MPMoPubAd>)ad withImpressionData:(MPImpressionData * _Nullable)impressionData;

// for static native ads
- (void)mopubAd:(id<MPMoPubAd>)ad didTrackImpressionWithImpressionData:(MPImpressionData * _Nullable)impressionData

Example

// Example for Adplacer
- (void)mopubAdPlacer:(id<MPMoPubAdPlacer>)adPlacer didTrackImpressionForAd:(id<MPMoPubAd>)ad withImpressionData:(MPImpressionData * _Nullable)impressionData
{
    // impressionData
    if (impressionData == nil)
    {
        return;
    }
    
    // impressionObject
    NSError *jsonSerializationError = nil;
    NSObject *impressionObject = [NSJSONSerialization JSONObjectWithData:impressionData.jsonRepresentation options:0 error:&jsonSerializationError];
    
    // impressionDictionary
    NSDictionary *impressionDictionary = [impressionObject isKindOfClass:NSDictionary.class] ? (NSDictionary *)impressionObject : nil;
    if (impressionDictionary == nil)
    {
        return;
    }
}
// Example for static native
- (void)mopubAd:(id<MPMoPubAd>)ad didTrackImpressionWithImpressionData:(MPImpressionData * _Nullable)impressionData
{
    // impressionData
    if (impressionData == nil)
    {
        return;
    }
    
    // impressionObject
    NSError *jsonSerializationError = nil;
    NSObject *impressionObject = [NSJSONSerialization JSONObjectWithData:impressionData.jsonRepresentation options:0 error:&jsonSerializationError];
 
    // impressionDictionary
    NSDictionary *impressionDictionary = [impressionObject isKindOfClass:NSDictionary.class] ? (NSDictionary *)impressionObject : nil;
    if (impressionDictionary == nil)
    {
        return;
    }
    
}

Send MoPub ILRD Data to Third-Party Attribution and Analytics Vendors

Once you are receiving impression data, you can feed it to your internal Business Intelligence (BI) tools or send it to third-party attribution and analytics providers for further analysis. MoPub has collaborated with the following attribution & analytics vendors to support MoPub’s impression-level revenue data: Adjust, AppsFlyer, Branch, Kochava, Singular, Soomla, and Tenjin

Each third-party attribution and analytics vendor has its own required format for receiving ILRD data. Specifications to send your data to your third-party attribution and analytics vendors are below.

Example to send MoPub ILRD to Internal BI tool or Firebase

Note: The below sample is applicable assuming the publisher has Firebase SDK in the app.

- (void)mopubAd:(id<MPMoPubAd>)ad didTrackImpressionWithImpressionData:(MPImpressionData * _Nullable)impressionData
{
    
    static NSString *const kFIREventImpressionData= @"ad_impression_shown"
    static NSString *const kFIREventViewAdunit = @"adunit"
    static NSString *const kFIREventViewAdunitFormat = @"adunit_format"
    static NSString *const kFIREventViewCurrency = @"currency"
    static NSString *const kFIREventViewPublisherRevenue = @"publisher_revenue"
    static NSString *const kFIREventViewNetworkName = @"network_name"
    static NSString *const kFIREventViewCountry = @"country"
    static NSString *const kFIREventViewPrecision = @"precision"


    // Feed impression data into internal tools or send to third-party analytics
    if (impressionData != nil)
    {
        [FIRApp configure];
        [FIRAnalytics logEventWithName:kFIREventImpressionData
                    parameters:@{
                                 kFIREventViewAdunit:impressionData.adunit],
                                 kFIREventViewAdunitFormat:impressionData.adunit,
                                 kFIREventViewCurrency:impressionData.currency,
                                 kFIREventViewPublisherRevenue:impressionData.publisherRevenue,
                                 kFIREventViewNetworkName:impressionData.networkName,
                                 kFIREventViewCountry:impressionData.country,
                                 kFIREventViewPrecision:impressionData.precision
                                 }];
    }
}

Last updated November 07, 2019

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2019 MoPub (a division of Twitter, Inc.)