Prasyarat
Selesaikan penyiapan peristiwa kustom.
Meminta iklan native
Saat item baris peristiwa kustom dicapai dalam rantai mediasi waterfall,
metode loadNativeAd:adConfiguration:completionHandler:
akan dipanggil pada
nama class yang Anda berikan saat membuat peristiwa
kustom. Dalam hal ini,
metode tersebut ada di SampleCustomEvent
, yang kemudian memanggil
metode loadNativeAd:adConfiguration:completionHandler:
di
SampleCustomEventNative
.
Untuk meminta iklan native, buat atau ubah class yang mengimplementasikan
GADMediationAdapter
dan loadNativeAd:adConfiguration:completionHandler:
. Jika
class yang memperluas GADMediationAdapter
sudah ada, terapkan
loadNativeAd:adConfiguration:completionHandler:
di sana. Selain itu, buat
class baru untuk mengimplementasikan GADMediationNativeAd
.
Dalam contoh peristiwa kustom,
SampleCustomEvent
mengimplementasikan
antarmuka GADMediationAdapter
, lalu mendelegasikan ke
SampleCustomEventNative
.
Swift
import GoogleMobileAds class SampleCustomEvent: NSObject, GADMediationAdapter { fileprivate var nativeAd: SampleCustomEventNativeAd? func loadNativeAd( for adConfiguration: GADMediationNativeAdConfiguration, 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` bertanggung jawab atas tugas-tugas berikut:
Memuat iklan native
Mengimplementasikan protokol
GADMediationNativeAd
.Menerima dan melaporkan callback peristiwa iklan ke Google Mobile Ads SDK
Parameter opsional yang ditentukan di UI Ad Manager
disertakan dalam konfigurasi iklan.
Parameter ini dapat diakses melalui
adConfiguration.credentials.settings[@"parameter"]
. Parameter ini
biasanya adalah ID unit iklan yang diperlukan SDK jaringan iklan saat
membuat instance objek iklan.
Swift
class SampleCustomEventNativeAd: NSObject, GADMediationNativeAd { /// 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: GADMediationNativeAdEventDelegate? /// Completion handler called after ad load var completionHandler: GADMediationNativeLoadCompletionHandler? func loadNativeAd( for adConfiguration: GADMediationNativeAdConfiguration, completionHandler: @escaping GADMediationNativeLoadCompletionHandler ) { let adLoader = SampleNativeAdLoader() let sampleRequest = SampleNativeAdRequest() // The 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: GADAdLoaderOptions in options { if let imageOptions = loaderOptions as? GADNativeAdImageAdLoaderOptions { 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? GADNativeAdMediaAdLoaderOptions { switch mediaOptions.mediaAspectRatio { case GADMediaAspectRatio.landscape: sampleRequest.preferredImageOrientation = NativeAdImageOrientation.landscape case GADMediaAspectRatio.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]; // The 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]; }
Baik iklan berhasil diambil atau mengalami error, Anda
akan memanggil GADMediationNativeAdLoadCompletionHandler
. Jika berhasil, teruskan class yang mengimplementasikan GADMediationNativeAd
dengan nilai nil
untuk parameter error; jika gagal, teruskan error yang Anda temui.
Biasanya, metode ini diterapkan di dalam callback dari
SDK pihak ketiga yang diterapkan adaptor Anda. Untuk contoh ini, Sample SDK
memiliki SampleNativeAdDelegate
dengan callback yang relevan:
Swift
func adLoader( _ adLoader: SampleNativeAdLoader, didReceive nativeAd: SampleNativeAd ) { extraAssets = [ SampleCustomEventConstantsSwift.awesomenessKey: nativeAd.degreeOfAwesomeness ?? "" ] if let image = nativeAd.image { images = [GADNativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [GADNativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] } if let mappedIcon = nativeAd.icon { icon = GADNativeAdImage(image: mappedIcon) } else { let iconURL = URL(fileURLWithPath: nativeAd.iconURL) icon = GADNativeAdImage(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); }
Iklan native peta
SDK yang berbeda memiliki format unik sendiri untuk iklan native. Satu kolom mungkin menampilkan objek yang berisi kolom "judul", misalnya, sementara kolom lainnya mungkin memiliki "judul utama". Selain itu, metode yang digunakan untuk melacak tayangan dan memproses klik dapat bervariasi dari satu SDK ke SDK lainnya.
Untuk mengatasi masalah ini, saat peristiwa kustom menerima objek iklan native dari
SDK yang dimediasi, peristiwa tersebut harus menggunakan class yang mengimplementasikan GADMediationNativeAd
,
seperti SampleCustomEventNativeAd
, untuk "memetakan" objek iklan native SDK yang dimediasi
sehingga cocok dengan antarmuka yang diharapkan oleh Google Mobile Ads SDK.
Sekarang, mari kita lihat lebih dekat detail penerapan untuk
SampleCustomEventNativeAd
.
Menyimpan pemetaan
GADMediationNativeAd
diharapkan menerapkan properti tertentu yang
dipetakan dari properti SDK lain:
Swift
var nativeAd: SampleNativeAd? var headline: String? { return nativeAd?.headline } var images: [GADNativeAdImage]? var body: String? { return nativeAd?.body } var icon: GADNativeAdImage? 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; }
Beberapa jaringan yang dimediasi dapat menyediakan aset tambahan selain yang ditentukan oleh
Google Mobile Ads SDK. Protokol GADMediationNativeAd
menyertakan metode
yang disebut extraAssets
yang digunakan Google Mobile Ads SDK untuk mengambil
aset "tambahan" ini dari mapper Anda.
Aset gambar peta
Pemetaan aset gambar lebih rumit daripada pemetaan jenis data yang lebih sederhana seperti NSString
atau double
. Gambar mungkin didownload secara otomatis atau
ditampilkan sebagai nilai URL. Kepadatan pikselnya juga dapat bervariasi.
Untuk membantu Anda mengelola detail ini, Google Mobile Ads SDK menyediakan
class GADNativeAdImage
. Informasi aset gambar (baik objek UIImage
yang sebenarnya maupun hanya nilai NSURL
) harus ditampilkan ke Google Mobile Ads SDK
menggunakan class ini.
Berikut adalah cara class mapper menangani pembuatan GADNativeAdImage
untuk menyimpan
gambar ikon:
Swift
if let image = nativeAd.image { images = [GADNativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [GADNativeAdImage(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] ]; }
Peristiwa tayangan dan klik
Google Mobile Ads SDK dan SDK mediasi perlu mengetahui kapan tayangan atau klik terjadi, tetapi hanya satu SDK yang perlu melacak peristiwa ini. Ada dua pendekatan berbeda yang dapat digunakan peristiwa kustom, bergantung pada apakah SDK yang dimediasi mendukung pelacakan tayangan iklan dan klik secara mandiri.
Melacak klik dan tayangan dengan Google Mobile Ads SDK
Jika SDK yang dimediasi tidak melakukan pelacakan tayangan iklan dan kliknya sendiri, tetapi
menyediakan metode untuk mencatat klik dan tayangan iklan, Google Mobile Ads SDK dapat
melacak peristiwa ini dan memberi tahu adaptor. Protokol GADMediationNativeAd
menyertakan dua metode: didRecordImpression:
dan
didRecordClickOnAssetWithName:view:viewController:
yang dapat diterapkan oleh peristiwa kustom
untuk memanggil metode yang sesuai pada objek iklan native yang dimediasi:
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]; } }
Karena class yang menerapkan protokol GADMediationNativeAd
menyimpan referensi ke objek iklan native Sample SDK, class tersebut dapat memanggil
metode yang sesuai pada objek tersebut untuk melaporkan klik atau tayangan. Perhatikan bahwa
metode didRecordClickOnAssetWithName:view:viewController:
mengambil satu
parameter: objek View
yang sesuai dengan aset iklan native yang menerima
klik.
Melacak klik dan tayangan iklan dengan SDK yang dimediasi
Beberapa SDK yang dimediasi mungkin lebih memilih untuk melacak klik dan tayangan sendiri. Dalam
hal ini, Anda harus menerapkan metode handlesUserClicks
dan
handlesUserImpressions
seperti yang ditunjukkan dalam cuplikan di bawah. Dengan menampilkan
YES
, Anda menunjukkan bahwa peristiwa kustom bertanggung jawab untuk melacak
peristiwa ini dan akan memberi tahu Google Mobile Ads SDK saat peristiwa ini terjadi.
Peristiwa kustom yang mengganti pelacakan klik dan tayangan dapat menggunakan
pesan didRenderInView:
untuk meneruskan tampilan iklan native ke objek iklan native
SDK yang dimediasi agar SDK yang dimediasi dapat melakukan pelacakan yang sebenarnya. SDK contoh
dari project contoh peristiwa kustom kami (tempat cuplikan kode panduan ini
diambil) tidak menggunakan pendekatan ini, tetapi jika menggunakan pendekatan ini, kode peristiwa kustom
akan memanggil metode setNativeAdView:view:
seperti yang ditunjukkan dalam cuplikan di bawah:
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]; }
Meneruskan peristiwa mediasi ke Google Mobile Ads SDK
Setelah Anda memanggil
GADMediationNativeLoadCompletionHandler
dengan iklan yang dimuat, objek delegasi GADMediationNativeAdEventDelegate
yang ditampilkan kemudian dapat digunakan oleh adaptor untuk meneruskan peristiwa presentasi dari
SDK pihak ketiga ke Google Mobile Ads SDK.
Peristiwa kustom Anda harus meneruskan callback ini sebanyak mungkin, sehingga aplikasi Anda menerima peristiwa yang setara ini dari Google Mobile Ads SDK. Berikut adalah contoh penggunaan callback:
Tindakan ini akan menyelesaikan penerapan peristiwa kustom untuk iklan native. Contoh lengkap tersedia di GitHub.