Integrate Impression-Level Revenue Data

Before you begin:

  • First read our Impression-Level Revenue Data (ILRD) guide to understand the flow of events that you will implement below.

  • Make sure you have integrated MoPub SDK v5.9.0 or higher.

  • Note that there a known issue exclusive to Unity affecting SDK versions lower than 5.9.0. When parsing impression data, if the ILRD field has a null value, it may cause the app to crash, or you may notice other problems. To avoid this, upgrade to MoPub Unity SDK v5.9.0.

Register for the Impression Event

MoPub Unity SDK v5.7.0 and higher includes a foreground impression callback, OnImpressionTrackedEvent, that you can use to be notified about impression events. Since this impression callback is run in the Unity foreground, a fullscreen ad will prevent the callback from firing until the ad is dismissed – and the Unity Player is resumed.

The following example illustrates how to register to the foreground impression event.

private void OnEnable() {

  MoPubManager.OnImpressionTrackedEvent += OnImpressionTrackedEvent;

}

private void OnImpressionTrackedEvent(string adUnitId, MoPub.ImpressionData impressionData)
{
   // Feed impression data into internal tools or send to third-party analytics
   // NOTE: Will be delayed until Unity Player resumes if the app is backgrounded or a fullscreen ad is showing
}

MoPubUnity SDK v5.14.0 introduced a background impression callback, OnImpressionTrackedEventBg, which is triggered immediately when the impression happens, regardless of the Unity Player state. Since background callbacks are triggered in a background thread instead of the Unity main thread, you may not have access to UnityEngine APIs or your scene hierarchy in this scope. As such, we recommend you use this background impression callback only to forward impression data to internal tools or third-party analytics.

You may subscribe to both foreground and background impression events, yet when you do so only the background callback will include the impression data (to prevent accidental duplication).

The following example illustrates how to register to the background impression event.

private void OnEnable() {

  MoPubManager.OnImpressionTrackedEventBg += OnImpressionTrackedEventBg;

}

private void OnImpressionTrackedEventBg(string adUnitId, MoPub.ImpressionData impressionData)
{
   // Feed impression data into internal tools or send to third-party analytics
   // NOTE: Will trigger immediately, regardless of Unity Player state
}

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

Send Data to Other Tools or Vendors

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
Google Analytics for Firebase Refer to the example below
Kochava Kochava format specifications
Singular Singular format specifications
Soomla Soomla format specifications
Tenjin Tenjin format specifications

We recommend that you call tenjin.SubscribeMoPubImpressions() after initializing the Tenjin SDK, as documented in the Tenjin readme. Call this method as early as possible in the lifecycle of the app, so that Tenjin can receive ILRD events as soon as they are emitted. The minimum Tenjin SDK version required is 1.10.2. If you have any questions, contact the Tenjin support team.
GameAnalytics (BETA) GameAnalytics format specifications

Example

MoPub officially partners with Google Analytics for Firebase. Follow this example (which assumes that you have the Firebase SDK in your app) to send MoPub ILRD to Google Analytics for Firebase. You can also use this code snippet as an example of integrating an internal BI tool.

// REGISTER TO LISTEN TO THE EVENT FROM MOPUB SDK
    private void OnEnable() {
        MoPubManager.OnImpressionTrackedEvent += OnImpressionTrackedEvent;
    }

    private void OnImpressionTrackedEvent(string adUnitId, MoPub.ImpressionData impressionData)
    {
        // Feed impression data into internal tools or send to third-party analytics
        if (impressionData != null) {
          var myImpressionObject = JsonUtility.FromJson<ImpressionObject>(impressionData.JsonRepresentation);
          var impressionParameters = new[] {
              new Firebase.Analytics.Parameter("ad_platform", “MoPub”),
              new Firebase.Analytics.Parameter("ad_source", myImpressionObject.network_name),
              new Firebase.Analytics.Parameter("ad_unit_name", myImpressionObject.adunit_name),
              new Firebase.Analytics.Parameter("ad_format", myImpressionObject.adunit_format),
              new Firebase.Analytics.Parameter("value", myImpressionObject.publisher_revenue),
              new Firebase.Analytics.Parameter("currency", myImpressionObject.currency),
              new Firebase.Analytics.Parameter("precision", myImpressionObject.precision)
          };
          Firebase.Analytics.FirebaseAnalytics.LogEvent("ad_impression", impressionParameters);
        }
    }

    [Serializable]
    public class ImpressionObject
    {
        public string adunit_id;
        public string adunit_name;
        public string adunit_format;
        public string app_version;
        public string id;
        public string currency;
        public string publisher_revenue;
        public string network_name;
        public string network_placement_id;
        public string adgroup_id;
        public string adgroup_name;
        public string adgroup_type;
        public string adgroup_priority;
        public string country;
        public string precision;
    }

Last updated March 30, 2021

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.

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