必要條件
完成自訂事件設定。
請求原生廣告
當刊登序列中介服務鏈中到達自訂事件委刊項時,系統會使用您在建立自訂事件時提供的類別名稱呼叫the loadNativeAd:adConfiguration:completionHandler:
method 。在此情況下,該方法位於 SampleCustomEvent
中,接著在 SampleCustomEventNative
中呼叫the loadNativeAd:adConfiguration:completionHandler:
method 。
如要請求原生廣告,請建立或修改實作 GADMediationAdapter
和 loadNativeAd:adConfiguration:completionHandler:
的類別。如果擴充 GADMediationAdapter
的類別已存在,請在該類別實作 loadNativeAd:adConfiguration:completionHandler:
。此外,您也可以建立新類別來實作 GADMediationNativeAd
。
在自訂事件範例中,SampleCustomEvent
會實作the GADMediationAdapter
interface ,然後委派給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
」負責以下工作:
載入原生廣告
導入
GADMediationNativeAd
protocol接收及回報 Google Mobile Ads SDK 的廣告事件回呼
廣告設定包含 AdMob UI 中定義的選用參數。您可以透過 adConfiguration.credentials.settings[@"parameter"]
存取這個參數。這個參數通常是廣告聯播網 SDK 在執行個體化廣告物件時所需的廣告單元 ID。
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]; }
無論廣告是否成功擷取還是發生錯誤,您都需要呼叫 GADMediationNativeAdLoadCompletionHandler
。如果事件成功,請傳遞用於實作 GADMediationNativeAd
且為錯誤參數使用 nil
值的類別;如果發生失敗,請傳遞您遇到的錯誤。
一般來說,這些方法是在轉接程式實作的第三方 SDK 回呼內實作。在這個範例中,範例 SDK 的 SampleNativeAdDelegate
含有相關回呼:
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); }
對應原生廣告
不同的 SDK 各有專屬的原生廣告格式。舉例來說,其中一個可能會傳回包含「title」欄位的物件,而另一個可能有「headline」欄位。此外,用於追蹤曝光和處理點擊的方法可能依 SDK 而異。
為解決這些問題,當自訂事件從其中介服務 SDK 收到原生廣告物件時,應使用導入 GADMediationNativeAd
(例如 SampleCustomEventNativeAd
) 的類別來「對應」中介服務 SDK 的原生廣告物件,讓該物件符合 Google Mobile Ads SDK 預期的介面。
我們現在將進一步說明 SampleCustomEventNativeAd
的實作詳細資料。
儲存對應關係
GADMediationNativeAd
應會實作從其他 SDK 屬性對應的特定屬性:
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; }
除了 Google Mobile Ads SDK 所定義的素材資源外,某些中介聯播網還可提供額外的素材資源。GADMediationNativeAd
通訊協定包含名為 extraAssets
的方法,Google Mobile Ads SDK 會使用此方法從對應器中擷取上述任何「額外」素材資源。
對應圖片素材資源
對應圖片素材資源會比對應較簡單的資料類型 (例如 NSString
或 double
) 複雜。系統可能會自動下載圖片,或以網址值的形式傳回圖片。他們的像素密度也可能有所差異。
為協助您管理這些詳細資料,Google Mobile Ads SDK 提供 GADNativeAdImage
類別。圖片素材資源資訊 (無論是實際 UIImage
物件或只有 NSURL
值) 應使用此類別傳回 Google Mobile Ads SDK。
以下說明對應工具類別如何建立 GADNativeAdImage
來保存圖示圖片:
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] ]; }
曝光和點擊事件
Google Mobile Ads SDK 和中介服務 SDK 都必須知道曝光或點擊何時發生,但只需要一個 SDK 就能追蹤這些事件。自訂事件可採用兩種不同方法,具體視中介 SDK 是否支援自行追蹤曝光和點擊的方式而定。
使用 Google Mobile Ads SDK 追蹤點擊和曝光
如果中介服務 SDK 不會自行執行曝光和點擊追蹤,但提供記錄點擊和曝光的方法,Google Mobile Ads SDK 就能追蹤這些事件並通知轉接程式。GADMediationNativeAd
protocol 包含兩種方法:didRecordImpression:
以及 didRecordClickOnAssetWithName:view:viewController:
自訂事件可實作,用於在中介原生廣告物件呼叫相應的方法:
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]; } }
由於導入 GADMediationNativeAd
protocol通訊協定的類別會保留對範例 SDK 的原生廣告物件的參照,因此可以針對該物件呼叫適當的方法,藉此回報點擊或曝光。請注意,didRecordClickOnAssetWithName:view:viewController:
方法使用單一參數:與接收點擊的原生廣告素材資源相對應的 View
物件。
使用中介服務 SDK 追蹤點擊和曝光
有些採用中介服務的 SDK 可能會想自行追蹤點擊和曝光次數,在這種情況下,應實作 handlesUserClicks
和 handlesUserImpressions
方法,如以下程式碼片段所示。傳回 YES
,即表示您表示自訂事件負責追蹤這些事件,並在這些事件發生時通知 Google Mobile Ads SDK。
如果自訂事件會覆寫點擊和曝光追蹤,可以使用 didRenderInView:
訊息將原生廣告的檢視畫面傳送至中介 SDK 的原生廣告物件,讓中介服務 SDK 進行實際追蹤。自訂事件範例專案中的範例 SDK (這是本指南的程式碼片段的來源) 並未使用這個方法。如果支援,自訂事件程式碼就會呼叫 setNativeAdView:view:
方法,如以下程式碼片段所示:
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]; }
將中介服務事件轉送至 Google Mobile Ads SDK
使用已載入的廣告呼叫 GADMediationNativeLoadCompletionHandler
後,轉接程式即可使用傳回的 GADMediationNativeAdEventDelegate
委派物件,將顯示事件從第三方 SDK 轉送至 Google Mobile Ads SDK。
您的自訂事件必須盡可能轉送這些回呼,才能讓應用程式從 Google Mobile Ads SDK 接收這些對等事件。以下是回呼的使用範例:
系統隨即會完成原生廣告的自訂事件導入。您可以在 GitHub 取得完整範例。