Prerequisites
Complete the custom events setup .
Request a native ad
When the custom event line item is reached in the waterfall mediation chain,
the loadNativeAd:adConfiguration:completionHandler:
method is called on the
class name you provided when creating a custom
event
. In this case,
that method is in SampleCustomEvent
, which then calls
the loadNativeAd:adConfiguration:completionHandler:
method in SampleCustomEventNative
.
To request a native ad, create or modify a class that implements GADMediationAdapter
and loadNativeAd:adConfiguration:completionHandler:
. If
a class that extends GADMediationAdapter
already exists, implement loadNativeAd:adConfiguration:completionHandler:
there. Additionally, create a
new class to implement GADMediationNativeAd
.
In our custom event example, SampleCustomEvent
implements
the GADMediationAdapter
interface and then delegates to SampleCustomEventNative
.
Swift
import GoogleMobileAds class SampleCustomEvent : NSObject , MediationAdapter { fileprivate var nativeAd : SampleCustomEventNativeAd ? func loadNativeAd ( for adConfiguration : MediationNativeAdConfiguration , completionHandler : @ escaping GADMediationNativeAdLoadCompletionHandler ) { self . nativeAd = SampleCustomEventNativeAd () self . nativeAd ?. loadNativeAd ( for : adConfiguration , completionHandler : completionHandler ) } }
Objective-C
#import "SampleCustomEvent.h" @implementation SampleCustomEvent SampleCustomEventNativeAd * sampleNativeAd ; - ( void ) loadNativeAdForAdConfiguration: ( GADMediationNativeAdConfiguration * ) adConfiguration completionHandler : ( GADMediationNativeAdLoadCompletionHandler ) completionHandler { sampleNative = [[ SampleCustomEventNativeAd alloc ] init ]; [ sampleNative loadNativeAdForAdConfiguration : adConfiguration completionHandler : completionHandler ]; }
SampleCustomEventNative` is responsible for the following tasks:
-
Loading the native ad
-
Implementing the
GADMediationNativeAdprotocol. -
Receiving and reporting ad event callbacks to Google Mobile Ads SDK.
The optional parameter defined in the AdMob UI is
included in the ad configuration.
The parameter can be accessed through adConfiguration.credentials.settings[@"parameter"]
. This parameter is
typically an ad unit identifier that an ad network SDK requires when
instantiating an ad object.
Swift
class SampleCustomEventNativeAd : NSObject , MediationNativeAd { /// The Sample Ad Network native ad. var nativeAd : SampleNativeAd ? /// The ad event delegate to forward ad rendering events to the Google Mobile /// Ads SDK. var delegate : MediationNativeAdEventDelegate ? /// Completion handler called after ad load var completionHandler : GADMediationNativeLoadCompletionHandler ? func loadNativeAd ( for adConfiguration : MediationNativeAdConfiguration , completionHandler : @ escaping GADMediationNativeLoadCompletionHandler ) { let adLoader = SampleNativeAdLoader () let sampleRequest = SampleNativeAdRequest () // Google Mobile Ads SDK requires the image assets to be downloaded // automatically unless the publisher specifies otherwise by using the // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If // your network doesn't have an option like this and instead only ever // returns URLs for images (rather than the images themselves), your adapter // should download image assets on behalf of the publisher. This should be // done after receiving the native ad object from your network's SDK, and // before calling the connector's adapter:didReceiveMediatedNativeAd: method. sampleRequest . shouldDownloadImages = true sampleRequest . preferredImageOrientation = NativeAdImageOrientation . any sampleRequest . shouldRequestMultipleImages = false let options = adConfiguration . options for loaderOptions : AdLoaderOptions in options { if let imageOptions = loaderOptions as ? NativeAdImageAdLoaderOptions { sampleRequest . shouldRequestMultipleImages = imageOptions . shouldRequestMultipleImages // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is // YES, the adapter should send just the URLs for the images. sampleRequest . shouldDownloadImages = ! imageOptions . disableImageLoading } else if let mediaOptions = loaderOptions as ? NativeAdMediaAdLoaderOptions { switch mediaOptions . mediaAspectRatio { case MediaAspectRatio . landscape : sampleRequest . preferredImageOrientation = NativeAdImageOrientation . landscape case MediaAspectRatio . portrait : sampleRequest . preferredImageOrientation = NativeAdImageOrientation . portrait default : sampleRequest . preferredImageOrientation = NativeAdImageOrientation . any } } } // This custom event uses the server parameter to carry an ad unit ID, which // is the most common use case. adLoader . delegate = self adLoader . adUnitID = adConfiguration . credentials . settings [ "parameter" ] as ? String self . completionHandler = completionHandler adLoader . fetchAd ( sampleRequest ) } }
Objective-C
#import "SampleCustomEventNativeAd.h" @interface SampleCustomEventNativeAd () < SampleNativeAdDelegate , GADMediationNativeAd > { /// The sample native ad. SampleNativeAd * _nativeAd ; /// The completion handler to call when the ad loading succeeds or fails. GADMediationNativeLoadCompletionHandler _loadCompletionHandler ; /// The ad event delegate to forward ad rendering events to the Google Mobile /// Ads SDK. id<GADMediationNativeAdEventDelegate > _adEventDelegate ; } @end - ( void ) loadNativeAdForAdConfiguration : ( GADMediationNativeAdConfiguration * ) adConfiguration completionHandler :( GADMediationNativeLoadCompletionHandler ) completionHandler { __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT ; __block GADMediationNativeLoadCompletionHandler originalCompletionHandler = [ completionHandler copy ]; _loadCompletionHandler = ^ id<GADMediationNativeAdEventDelegate > ( _Nullable id<GADMediationNativeAd > ad , NSError * _Nullable error ) { // Only allow completion handler to be called once. if ( atomic_flag_test_and_set ( & completionHandlerCalled )) { return nil ; } id<GADMediationNativeAdEventDelegate > delegate = nil ; if ( originalCompletionHandler ) { // Call original handler and hold on to its return value. delegate = originalCompletionHandler ( ad , error ); } // Release reference to handler. Objects retained by the handler will also // be released. originalCompletionHandler = nil ; return delegate ; }; SampleNativeAdLoader * adLoader = [[ SampleNativeAdLoader alloc ] init ]; SampleNativeAdRequest * sampleRequest = [[ SampleNativeAdRequest alloc ] init ]; // Google Mobile Ads SDK requires the image assets to be downloaded // automatically unless the publisher specifies otherwise by using the // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If // your network doesn't have an option like this and instead only ever returns // URLs for images (rather than the images themselves), your adapter should // download image assets on behalf of the publisher. This should be done after // receiving the native ad object from your network's SDK, and before calling // the connector's adapter:didReceiveMediatedNativeAd: method. sampleRequest . shouldDownloadImages = YES ; sampleRequest . preferredImageOrientation = NativeAdImageOrientationAny ; sampleRequest . shouldRequestMultipleImages = NO ; sampleRequest . testMode = adConfiguration . isTestRequest ; for ( GADAdLoaderOptions * loaderOptions in adConfiguration . options ) { if ([ loaderOptions isKindOfClass : [ GADNativeAdImageAdLoaderOptions class ]]) { GADNativeAdImageAdLoaderOptions * imageOptions = ( GADNativeAdImageAdLoaderOptions * ) loaderOptions ; sampleRequest . shouldRequestMultipleImages = imageOptions . shouldRequestMultipleImages ; // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is // YES, the adapter should send just the URLs for the images. sampleRequest . shouldDownloadImages = ! imageOptions . disableImageLoading ; } else if ([ loaderOptions isKindOfClass :[ GADNativeAdMediaAdLoaderOptions class ]]) { GADNativeAdMediaAdLoaderOptions * mediaOptions = ( GADNativeAdMediaAdLoaderOptions * ) loaderOptions ; switch ( mediaOptions . mediaAspectRatio ) { case GADMediaAspectRatioLandscape : sampleRequest . preferredImageOrientation = NativeAdImageOrientationLandscape ; break ; case GADMediaAspectRatioPortrait : sampleRequest . preferredImageOrientation = NativeAdImageOrientationPortrait ; break ; default : sampleRequest . preferredImageOrientation = NativeAdImageOrientationAny ; break ; } } else if ([ loaderOptions isKindOfClass : [ GADNativeAdViewAdOptions class ]]) { _nativeAdViewAdOptions = ( GADNativeAdViewAdOptions * ) loaderOptions ; } } // This custom event uses the server parameter to carry an ad unit ID, which // is the most common use case. NSString * adUnit = adConfiguration . credentials . settings [ @"parameter" ]; adLoader . adUnitID = adUnit ; adLoader . delegate = self ; [ adLoader fetchAd : sampleRequest ]; }
Whether the ad is successfully fetched or encounters an error, you
would call GADMediationNativeAdLoadCompletionHandler
. In the event of success,
pass through the class that implements GADMediationNativeAd
with a nil
value
for the error parameter; in the event of failure, pass through the error you
encountered.
Typically, these methods are implemented inside callbacks from the
third-party SDK your adapter implements. For this example, the Sample SDK
has a SampleNativeAdDelegate
with relevant callbacks:
Swift
func adLoader ( _ adLoader : SampleNativeAdLoader , didReceive nativeAd : SampleNativeAd ) { extraAssets = [ SampleCustomEventConstantsSwift . awesomenessKey : nativeAd . degreeOfAwesomeness ?? "" ] if let image = nativeAd . image { images = [ NativeAdImage ( image : image )] } else { let imageUrl = URL ( fileURLWithPath : nativeAd . imageURL ) images = [ NativeAdImage ( url : imageUrl , scale : nativeAd . imageScale )] } if let mappedIcon = nativeAd . icon { icon = NativeAdImage ( image : mappedIcon ) } else { let iconURL = URL ( fileURLWithPath : nativeAd . iconURL ) icon = NativeAdImage ( url : iconURL , scale : nativeAd . iconScale ) } adChoicesView = SampleAdInfoView () self . nativeAd = nativeAd if let handler = completionHandler { delegate = handler ( self , nil ) } } func adLoader ( _ adLoader : SampleNativeAdLoader , didFailToLoadAdWith errorCode : SampleErrorCode ) { let error = SampleCustomEventUtilsSwift . SampleCustomEventErrorWithCodeAndDescription ( code : SampleCustomEventErrorCodeSwift . SampleCustomEventErrorAdLoadFailureCallback , description : "Sample SDK returned an ad load failure callback with error code: \( errorCode ) " ) if let handler = completionHandler { delegate = handler ( nil , error ) } }
Objective-C
- ( void ) adLoader: ( SampleNativeAdLoader * ) adLoader didReceiveNativeAd :( SampleNativeAd * ) nativeAd { if ( nativeAd . image ) { _images = @[ [[ GADNativeAdImage alloc ] initWithImage : nativeAd . image ] ] ; } else { NSURL * imageURL = [[ NSURL alloc ] initFileURLWithPath : nativeAd . imageURL ]; _images = @[ [[ GADNativeAdImage alloc ] initWithURL : imageURL scale : nativeAd . imageScale ] ] ; } if ( nativeAd . icon ) { _icon = [[ GADNativeAdImage alloc ] initWithImage : nativeAd . icon ]; } else { NSURL * iconURL = [[ NSURL alloc ] initFileURLWithPath : nativeAd . iconURL ]; _icon = [[ GADNativeAdImage alloc ] initWithURL : iconURL scale : nativeAd . iconScale ]; } // The sample SDK provides an AdChoices view (SampleAdInfoView). If your SDK // provides image and click through URLs for its AdChoices icon instead of an // actual UIView, the adapter is responsible for downloading the icon image // and creating the AdChoices icon view. _adChoicesView = [[ SampleAdInfoView alloc ] init ]; _nativeAd = nativeAd ; _adEventDelegate = _loadCompletionHandler ( self , nil ); } - ( void ) adLoader: ( SampleNativeAdLoader * ) adLoader didFailToLoadAdWithErrorCode :( SampleErrorCode ) errorCode { NSError * error = SampleCustomEventErrorWithCodeAndDescription ( SampleCustomEventErrorAdLoadFailureCallback , [ NSString stringWithFormat : @"Sample SDK returned an ad load failure " @"callback with error code: %@" , errorCode ]); _adEventDelegate = _loadCompletionHandler ( nil , error ); }
Map native ads
Different SDKs have their own unique formats for native ads. One might return objects that contain a "title" field, for instance, while another might have "headline". Additionally, the methods used to track impressions and process clicks can vary from one SDK to another.
To address these issues, when a custom event receives a native ad object from
its mediated SDK, it should use a class that implements GADMediationNativeAd
,
like SampleCustomEventNativeAd
, to "map" the mediated SDK's native ad object
so it matches the interface expected by Google Mobile Ads SDK.
We now take a closer look at the implementation details for SampleCustomEventNativeAd
.
Store your mappings
GADMediationNativeAd
is expected to implement certain properties that are
mapped to from other SDK’s properties:
Swift
var nativeAd : SampleNativeAd ? var headline : String ? { return nativeAd ?. headline } var images : [ NativeAdImage ]? var body : String ? { return nativeAd ?. body } var icon : NativeAdImage ? var callToAction : String ? { return nativeAd ?. callToAction } var starRating : NSDecimalNumber ? { return nativeAd ?. starRating } var store : String ? { return nativeAd ?. store } var price : String ? { return nativeAd ?. price } var advertiser : String ? { return nativeAd ?. advertiser } var extraAssets : [ String : Any ]? { return [ SampleCustomEventConstantsSwift . awesomenessKey : nativeAd ?. degreeOfAwesomeness ?? "" ] } var adChoicesView : UIView ? var mediaView : UIView ? { return nativeAd ?. mediaView }
Objective-C
/// Used to store the ad's images. In order to implement the /// GADMediationNativeAd protocol, we use this class to return the images /// property. NSArray<GADNativeAdImage *> * _images ; /// Used to store the ad's icon. In order to implement the GADMediationNativeAd /// protocol, we use this class to return the icon property. GADNativeAdImage * _icon ; /// Used to store the ad's ad choices view. In order to implement the /// GADMediationNativeAd protocol, we use this class to return the adChoicesView /// property. UIView * _adChoicesView ; - ( nullable NSString * ) headline { return _nativeAd . headline ; } - ( nullable NSArray<GADNativeAdImage *> * ) images { return _images ; } - ( nullable NSString * ) body { return _nativeAd . body ; } - ( nullable GADNativeAdImage * ) icon { return _icon ; } - ( nullable NSString * ) callToAction { return _nativeAd . callToAction ; } - ( nullable NSDecimalNumber * ) starRating { return _nativeAd . starRating ; } - ( nullable NSString * ) store { return _nativeAd . store ; } - ( nullable NSString * ) price { return _nativeAd . price ; } - ( nullable NSString * ) advertiser { return _nativeAd . advertiser ; } - ( nullable NSDictionary<NSString * , id > * ) extraAssets { return @{ SampleCustomEventExtraKeyAwesomeness : _nativeAd . degreeOfAwesomeness } ; } - ( nullable UIView * ) adChoicesView { return _adChoicesView ; } - ( nullable UIView * ) mediaView { return _nativeAd . mediaView ; } - ( BOOL ) hasVideoContent { return self . mediaView != nil ; }
Some mediated networks can provide additional assets beyond those defined by
Google Mobile Ads SDK. The GADMediationNativeAd
protocol includes a method
called extraAssets
that Google Mobile Ads SDK uses to retrieve any of
these "extra" assets from your mapper.
Map image assets
Mapping image assets is more complicated than mapping simpler data
types like NSString
or double
. Images might be downloaded automatically or
returned as URL values. Their pixel density can also vary.
To help you manage these details, Google Mobile Ads SDK provides the GADNativeAdImage
class. Image asset information (whether it's actual UIImage
objects or just NSURL
values) should be returned to Google Mobile Ads SDK
using this class.
Here's how the mapper class handles creating a GADNativeAdImage
to hold the
icon image:
Swift
if let image = nativeAd . image { images = [ NativeAdImage ( image : image )] } else { let imageUrl = URL ( fileURLWithPath : nativeAd . imageURL ) images = [ NativeAdImage ( url : imageUrl , scale : nativeAd . imageScale )] }
Objective-C
if ( nativeAd . image ) { _images = @[ [[ GADNativeAdImage alloc ] initWithImage : nativeAd . image ] ] ; } else { NSURL * imageURL = [[ NSURL alloc ] initFileURLWithPath : nativeAd . imageURL ]; _images = @[ [[ GADNativeAdImage alloc ] initWithURL : imageURL scale : nativeAd . imageScale ] ] ; }
Impression and click events
Both Google Mobile Ads SDK and the mediated SDK need to know when an impression or click occurs, but only one SDK needs to track these events. There are two different approaches custom events can use, depending on whether the mediated SDK supports tracking impressions and clicks on its own.
Track clicks and impressions with Google Mobile Ads SDK
If the mediated SDK doesn't perform its own impression and click tracking but
provides methods to record clicks and impressions, Google Mobile Ads SDK can
track these events and notify the adapter. The GADMediationNativeAd
protocol
includes two methods: didRecordImpression:
and didRecordClickOnAssetWithName:view:viewController:
that custom events can
implement to call the corresponding method on the mediated native ad object:
Swift
func didRecordImpression () { nativeAd ?. recordImpression () } func didRecordClickOnAsset ( withName assetName : GADUnifiedNativeAssetIdentifier , view : UIView , wController : UIViewController ) { nativeAd ?. handleClick ( on : view ) }
Objective-C
- ( void ) didRecordImpression { if ( self . nativeAd ) { [ self . nativeAd recordImpression ]; } } - ( void ) didRecordClickOnAssetWithName: ( GADUnifiedNativeAssetIdentifier ) assetName view :( UIView * ) view viewController :( UIViewController * ) viewController { if ( self . nativeAd ) { [ self . nativeAd handleClickOnView : view ]; } }
Because the class that implements the GADMediationNativeAd
protocol holds a reference to the Sample SDK's native ad object, it can call the
appropriate method on that object to report a click or impression. Note that the didRecordClickOnAssetWithName:view:viewController:
method takes a single
parameter: the View
object corresponding to the native ad asset that received
the click.
Track clicks and impressions with the mediated SDK
Some mediated SDKs might prefer to track clicks and impressions on their own. In
that case, you should implement the handlesUserClicks
and handlesUserImpressions
methods as shown in the snippet below. By returning YES
, you indicate that the custom event takes responsibility for tracking
these events and will notify Google Mobile Ads SDK when these events occur.
Custom events that override click and impression tracking can use the didRenderInView:
message to pass the native ad's view to the mediated SDK's
native ad object to allow the mediated SDK to do the actual tracking. The sample
SDK from our custom event example project (from which this guide's code snippets
have been taken) doesn't use this approach' but if it did, the custom event code
would call the setNativeAdView:view:
method as shown in the snippet below:
Swift
func handlesUserClicks () -> Bool { return true } func handlesUserImpressions () -> Bool { return true } func didRender ( in view : UIView , clickableAssetViews : [ GADNativeAssetIdentifier : UIView ], nonclickableAssetViews : [ GADNativeAssetIdentifier : UIView ], viewController : UIViewController ) { // This method is called when the native ad view is rendered. Here you would pass the UIView // back to the mediated network's SDK. self . nativeAd ?. setNativeAdView ( view ) }
Objective-C
- ( BOOL ) handlesUserClicks { return YES ; } - ( BOOL ) handlesUserImpressions { return YES ; } - ( void ) didRenderInView: ( UIView * ) view clickableAssetViews :( NSDictionary<GADNativeAssetIdentifier , UIView *> * ) clickableAssetViews nonclickableAssetViews :( NSDictionary<GADNativeAssetIdentifier , UIView *> * ) nonclickableAssetViews viewController :( UIViewController * ) viewController { // This method is called when the native ad view is rendered. Here you would // pass the UIView back to the mediated network's SDK. Playing video using // SampleNativeAd's playVideo method [ _nativeAd setNativeAdView : view ]; }
Forward mediation events to Google Mobile Ads SDK
Once you've called GADMediationNativeLoadCompletionHandler
with a loaded ad, the returned GADMediationNativeAdEventDelegate
delegate
object can then be used by the adapter to forward presentation events from the
third-party SDK to Google Mobile Ads SDK.
It's important that your custom event forwards as many of these callbacks as possible, so that your app receives these equivalent events from Google Mobile Ads SDK. Here's an example of using callbacks:
This completes the custom events implementation for native ads. The full example is available on GitHub .
