Integrate Impression-Level Revenue Data

Before you begin:

There are two options for receiving impression-level revenue data. The first option is to receive impression data by registering to NSNotificationCenter. The second option is to set the impression callback delegate that is the most convenient for you, depending on the ad format.

Option 1. Register to NSNotificationCenter

Publishers and third-party SDKs can now subscribe to the events from NSNotificationCenter to be notified about impressions and to receive detailed impression data.

Simply call addObserver with the notification name constant kMPImpressionTrackedNotification (for Swift, use NSNotification.Name.mpImpressionTracked) to receive impression events. Call removeObserver to unsubscribe from impression-level revenue data events.

The MPImpressionData object, if included in the notification, is available in the notification object’s userInfo dictionary under the key kMPImpressionTrackedInfoImpressionDataKey. You can find more information 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
}

Option 2. Set the Impression Callback Delegate

We have provided an additional delegate (callback) to listen to impression events when an ad is shown. Most ad formats use the same delegate (MPMoPubAdDelegate), except for rewarded video, which uses MPRewardedVideoDelegate.

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

Rewarded Video Ads

Set the ad’s delegate object and implement the didTrackImpressionWithAdUnitID:impressionData: method to receive ad events.

MPRewardedVideoDelegate includes a variety of optional callbacks that you can use to be notified of events such as when a rewarded video has successfully loaded or when a rewarded video impression is fired. Refer to 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;
    }
}

Set the ad’s delegate object and implement the mopubAd:didTrackImpressionWithImpressionData: method to receive ad events.

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

MPMoPubAdDelegate includes an impression callback that you can use to be notified of impression events. Refer to 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

Set the ad’s delegate object and implement the mopubAd:didTrackImpressionWithImpressionData: method to receive ad events.

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

MPMoPubAdPlacerDelegate and MPNativeAdDelegate include impression callbacks that you can use to track impression events. Refer to 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 Data to Other Tools or 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.

Once you receive 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 a number of attribution and analytics vendors to support MoPub’s impression-level revenue data. Each vendor has their own format for receiving impression data. Our partners and their specifications are as follows:

Attribution/Analytics Vendor Format Specifications for Receiving ILRD
Adjust Adjust format specifications
AppsFlyer AppsFlyer format specifications
Branch Branch format specifications
Kochava Kochava format specifications
Singular Singular format specifications
Soomla Soomla format specifications
Tenjin Tenjin format specifications

Example

The following is an example of sending MoPub ILRD to an internal BI tool or Firebase. It assumes that you have the Firebase SDK in your app.

- (void)mopubAd:(id<MPMoPubAd>)ad didTrackImpressionWithImpressionData:(MPImpressionData * _Nullable)impressionData
{
    
    static NSString *const kFIREventImpressionData= @"ad_impression_shown"
    static NSString *const kFIREventViewAdunit = @"adunit_id"
    static NSString *const kFIREventViewAdunitFormat = @"adunit_format"
    static NSString *const kFIREventViewAppVersion = @"app_version"
    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_id,
                                 kFIREventViewAdunitFormat:impressionData.adunit,
                                 kFIREventViewAppVersion:impressionData.appVersion,
                                 kFIREventViewCurrency:impressionData.currency,
                                 kFIREventViewPublisherRevenue:impressionData.publisherRevenue,
                                 kFIREventViewNetworkName:impressionData.networkName,
                                 kFIREventViewCountry:impressionData.country,
                                 kFIREventViewPrecision:impressionData.precision
                                 }];
    }
}

Last updated May 22, 2020

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.

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