Impression-level ad revenue

    Select platform: Android (beta)New-selected Android iOS Unity

    When an impression occurs, GMA Next-Gen SDK provides ad revenue data associated with that impression. 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 the impression-level ad revenue data capture in your Android app.

    Prerequisites

    Each ad format has an onAdPaid event callback. During the lifecycle of an ad event, GMA Next-Gen SDK monitors impression events and invokes the handler with an earned value.

    The following example handles paid events for a rewarded ad:

    Kotlin

      ad 
 . 
 adEventCallback 
  
 = 
  
 object 
  
 : 
  
 RewardedAdEventCallback 
  
 { 
  
 override 
  
 fun 
  
 onAdPaid 
 ( 
 adValue 
 : 
  
 AdValue 
 ) 
  
 { 
  
 // Send the impression-level ad revenue information to your 
  
 // preferred analytics server directly within this callback. 
  
 // Extract the impression-level ad revenue data. 
  
 val 
  
 valueMicros 
  
 = 
  
 adValue 
 . 
 valueMicros 
  
 val 
  
 currencyCode 
  
 = 
  
 adValue 
 . 
 currencyCode 
  
 val 
  
 precisionType 
  
 = 
  
 adValue 
 . 
 precisionType 
  
 val 
  
 loadedAdSourceResponseInfo 
  
 = 
  
 ad 
 . 
 getResponseInfo 
 (). 
 loadedAdSourceResponseInfo 
  
 val 
  
 adSourceName 
  
 = 
  
 loadedAdSourceResponseInfo 
 ?. 
 name 
  
 val 
  
 adSourceId 
  
 = 
  
 loadedAdSourceResponseInfo 
 ?. 
 id 
  
 val 
  
 adSourceInstanceName 
  
 = 
  
 loadedAdSourceResponseInfo 
 ?. 
 instanceName 
  
 val 
  
 adSourceInstanceId 
  
 = 
  
 loadedAdSourceResponseInfo 
 ?. 
 instanceId 
  
 val 
  
 extras 
  
 = 
  
 ad 
 . 
 getResponseInfo 
 (). 
 responseExtras 
  
 val 
  
 mediationGroupName 
  
 = 
  
 extras 
 . 
 getString 
 ( 
 "mediation_group_name" 
 ) 
  
 val 
  
 mediationABTestName 
  
 = 
  
 extras 
 . 
 getString 
 ( 
 "mediation_ab_test_name" 
 ) 
  
 val 
  
 mediationABTestVariant 
  
 = 
  
 extras 
 . 
 getString 
 ( 
 "mediation_ab_test_variant" 
 ) 
  
 } 
  
 }

    Java

      ad 
 . 
 setAdEventCallback 
 ( 
  
 new 
  
 RewardedAdEventCallback 
 () 
  
 { 
  
 @Override 
  
 public 
  
 void 
  
 onAdPaid 
 ( 
 @NonNull 
  
 AdValue 
  
 value 
 ) 
  
 { 
  
 // Send the impression-level ad revenue information to your preferred 
  
 // analytics server directly within this callback. 
  
 // Extract the impression-level ad revenue data. 
  
 long 
  
 valueMicros 
  
 = 
  
 value 
 . 
 getValueMicros 
 (); 
  
 String 
  
 currencyCode 
  
 = 
  
 value 
 . 
 getCurrencyCode 
 (); 
  
 PrecisionType 
  
 precisionType 
  
 = 
  
 value 
 . 
 getPrecisionType 
 (); 
  
 AdSourceResponseInfo 
  
 loadedAdSourceResponseInfo 
  
 = 
  
 ad 
 . 
 getResponseInfo 
 (). 
 getLoadedAdSourceResponseInfo 
 (); 
  
 String 
  
 adSourceName 
  
 = 
  
 loadedAdSourceResponseInfo 
 . 
 getName 
 (); 
  
 String 
  
 adSourceId 
  
 = 
  
 loadedAdSourceResponseInfo 
 . 
 getId 
 (); 
  
 String 
  
 adSourceInstanceName 
  
 = 
  
 loadedAdSourceResponseInfo 
 . 
 getInstanceName 
 (); 
  
 String 
  
 adSourceInstanceId 
  
 = 
  
 loadedAdSourceResponseInfo 
 . 
 getInstanceId 
 (); 
  
 Bundle 
  
 extras 
  
 = 
  
 ad 
 . 
 getResponseInfo 
 (). 
 getResponseExtras 
 (); 
  
 String 
  
 mediationGroupName 
  
 = 
  
 extras 
 . 
 getString 
 ( 
 "mediation_group_name" 
 ); 
  
 String 
  
 mediationABTestName 
  
 = 
  
 extras 
 . 
 getString 
 ( 
 "mediation_ab_test_name" 
 ); 
  
 String 
  
 mediationABTestVariant 
  
 = 
  
 extras 
 . 
 getString 
 ( 
 "mediation_ab_test_variant" 
 ); 
  
 } 
  
 });

    Identify a custom event ad source name

    For custom event ad sources, the AdSourceResponseInfo.name property returns the ad source name Custom event . If you use multiple custom events, the ad source name isn't granular enough to distinguish between multiple custom events. To locate a specific custom event, do:

    1. Get the AdSourceResponseInfo.name property.
    2. Set a unique ad source name.

    The following example sets a unique ad source name for a custom event:

    Kotlin

      private 
  
 fun 
  
 getUniqueAdSourceName 
 ( 
 loadedAdapterResponseInfo 
 : 
  
 AdSourceResponseInfo 
 ): 
  
 String 
  
 { 
  
 var 
  
 adSourceName 
  
 = 
  
 loadedAdapterResponseInfo 
 . 
 name 
  
 if 
  
 ( 
 adSourceName 
  
 == 
  
 "Custom Event" 
 ) 
  
 { 
  
 if 
  
 ( 
  
 loadedAdapterResponseInfo 
 . 
 adapterClassName 
  
 == 
  
 "com.google.ads.mediation.sample.customevent.SampleCustomEvent" 
  
 ) 
  
 { 
  
 adSourceName 
  
 = 
  
 "Sample Ad Network (Custom Event)" 
  
 } 
  
 } 
  
 return 
  
 adSourceName 
 }

    Java

      private 
  
 String 
  
 getUniqueAdSourceName 
 ( 
 @NonNull 
  
 AdSourceResponseInfo 
  
 loadedAdapterResponseInfo 
 ) 
  
 { 
  
 String 
  
 adSourceName 
  
 = 
  
 loadedAdapterResponseInfo 
 . 
 getName 
 (); 
  
 if 
  
 ( 
 adSourceName 
 . 
 equals 
 ( 
 "Custom Event" 
 )) 
  
 { 
  
 if 
  
 ( 
 loadedAdapterResponseInfo 
  
 . 
 getAdapterClassName 
 () 
  
 . 
 equals 
 ( 
 "com.google.ads.mediation.sample.customevent.SampleCustomEvent" 
 )) 
  
 { 
  
 adSourceName 
  
 = 
  
 "Sample Ad Network (Custom Event)" 
 ; 
  
 } 
  
 } 
  
 return 
  
 adSourceName 
 ; 
 }

    For more information on the winning ad source, see Retrieve information about the ad response .

    App Attribution Partners (AAP) integration

    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 listener immediately once you create or get access to the ad object, and definitely before showing the ad. This makes sure that you don't miss any paid event callbacks.
    • Send the impression-level ad revenue information to your preferred analytics server immediately at the time the paid event callback is called. This makes sure that you don't accidentally drop any callbacks and avoids data discrepancies.

    AdValue

    AdValue is a class that represents the monetary value earned for an ad, including the value's currency code and its precision type encoded as follows.

    PrecisionType Description
    UNKNOWN An ad value that's unknown. This gets returned when LTV pingback is enabled but there isn't enough data available.
    ESTIMATED An ad value estimated from aggregated data.
    PUBLISHER_PROVIDED A publisher provided ad value, such as manual CPMs in a mediation group.
    PRECISE The precise value paid for this ad.

    In the case of AdMob Mediation, AdMob tries to provide an ESTIMATED value for ad sources that are optimized . For non-optimized ad sources, or in cases where there aren't enough aggregated data to report a meaningful estimation, the PUBLISHER_PROVIDED value is returned.

    Test impressions from bidding ad sources

    After an impression-level ad revenue event occurs for a bidding ad source through a test request, you receive only the following values:

    • UNKNOWN : indicates the precision type.
    • 0 : indicates the ad value.

    Previously, you might have seen the precision type as a value other than UNKNOWN and an ad value more than 0 .

    For details on sending a test ad request, see Enable test devices .
    Design a Mobile Site
    View Site in Mobile | Classic
    Share by: