Ön koşullar
Özel etkinlik kurulumunu tamamlayın.
Doğal reklam isteme
Şelale uyumlulaştırma zincirinde özel etkinlik satır öğesine ulaşıldığında, özel etkinlik oluştururken sağladığınız sınıf adınathe loadNativeAd:adConfiguration:completionHandler:
method çağrılır. Bu örnekte, bu yöntem SampleCustomEvent
içindedir ve daha sonrathe loadNativeAd:adConfiguration:completionHandler:
method içinde SampleCustomEventNative
çağrısı yapar.
Yerel reklam istemek için GADMediationAdapter
ve loadNativeAd:adConfiguration:completionHandler:
uygulayan bir sınıf oluşturun veya değiştirin. GADMediationAdapter
öğesini genişleten bir sınıf zaten varsa loadNativeAd:adConfiguration:completionHandler:
öğesini burada uygulayın. Ayrıca, GADMediationNativeAd
yöntemini uygulamak için yeni bir sınıf oluşturun.
Özel etkinlik örneğimizde SampleCustomEvent
,the GADMediationAdapter
interface uygulamasını uygular ve ardındanSampleCustomEventNative
öğesine yetki verir.
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
aşağıdaki görevlerden sorumludur:
Yerel reklam yükleniyor
GADMediationNativeAd
protocolReklam etkinliği geri çağırmalarını Google Mobile Ads SDK'sına alma ve raporlama
Kullanıcı arayüzünde tanımlanan Ad Manager isteğe bağlı parametre, reklam yapılandırmasına dahildir.
Parametreye adConfiguration.credentials.settings[@"parameter"]
üzerinden erişilebilir. Bu parametre, genellikle reklam ağı SDK'sının bir reklam nesnesini başlatırken ihtiyaç duyduğu reklam birimi tanımlayıcısıdır.
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]; }
Reklam başarıyla getirilsin veya bir hatayla karşılaşsın, GADMediationNativeAdLoadCompletionHandler
yöntemini çağırırsınız. Başarılı olmanız durumunda, hata parametresi için nil
değeriyle GADMediationNativeAd
uygulayan sınıfı geçin. Başarısız olması durumunda, karşılaştığınız hatayı iletin.
Genellikle bu yöntemler, bağdaştırıcınızın uyguladığı üçüncü taraf SDK'sından gelen geri çağırmaların içinde uygulanır. Bu örnekte Örnek SDK'da alakalı geri çağırma işlevleri olan bir SampleNativeAdDelegate
bulunur:
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); }
Yerel reklamları eşleme
Farklı SDK'ların yerel reklamlar için kendi benzersiz biçimleri vardır. Örneğin, biri "başlık" alanı içeren nesneleri döndürürken, diğeri "başlık" öğesine sahip olabilir. Ayrıca, gösterimleri izlemek ve tıklamaları işlemek için kullanılan yöntemler SDK'lar arasında farklılık gösterebilir.
Bu sorunları gidermek için bir özel etkinlik, uyumlulaştırılmış SDK'sından yerel reklam nesnesi aldığında, uyumlulaştırılmış SDK'nın yerel reklam nesnesini Google Mobile Ads SDK'sının beklediği arayüzle eşleşecek şekilde "eşlemek" için SampleCustomEventNativeAd
gibi GADMediationNativeAd
uygulayan bir sınıf kullanmalıdır.
Şimdi, SampleCustomEventNativeAd
için uygulama ayrıntılarını daha yakından inceleyelim.
Eşlemelerinizi saklama
GADMediationNativeAd
öğesinin, diğer SDK'nın özelliklerinden eşlenen belirli özellikleri uygulaması beklenir:
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; }
Bazı uyumlulaştırılmış ağlar, Google Mobile Ads SDK'sı tarafından tanımlananların ötesinde ek öğeler sağlayabilir. GADMediationNativeAd
protokolü, Google Mobile Ads SDK'sının bu "ek" öğeleri haritacınızdan almak için kullandığı extraAssets
adlı bir yöntem içerir.
Harita resmi öğeleri
Resim öğelerini eşlemek, NSString
veya double
gibi daha basit veri türlerini eşlemekten daha karmaşıktır. Resimler otomatik olarak indirilebilir
veya URL değerleri olarak döndürülebilir. Piksel yoğunlukları da değişiklik gösterebilir.
Bu ayrıntıları yönetmenize yardımcı olmak için Google Mobile Ads SDK'sı GADNativeAdImage
sınıfını sağlar. Resim öğesi bilgileri (gerçek UIImage
nesneleri veya sadece NSURL
değerleri), bu sınıf kullanılarak Google Mobile Ads SDK'sına döndürülmelidir.
Haritacı sınıfının simge resmini barındırmak için bir GADNativeAdImage
oluşturma işlemini nasıl ele aldığı aşağıda açıklanmıştır:
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] ]; }
Gösterim ve tıklama etkinlikleri
Hem Google Mobile Ads SDK'sının hem de uyumlulaştırılmış SDK'nın, bir gösterim veya tıklamanın ne zaman gerçekleştiğini bilmesi gerekir ancak bu etkinlikleri yalnızca bir SDK'nın izlemesi gerekir. Uyumlulaştırılan SDK'nın gösterim ve tıklama izlemeyi kendi başına destekleyip desteklememesine bağlı olarak özel etkinliklerin kullanabileceği iki farklı yaklaşım vardır.
Google Mobile Ads SDK'sı ile tıklamaları ve gösterimleri izleme
Uyumlulaştırılmış SDK kendi gösterim ve tıklama izleme işlemlerini gerçekleştirmiyorsa, ancak tıklamaları ve gösterimleri kaydetmeye yönelik yöntemler sağlıyorsa Google Mobile Ads SDK'sı bu etkinlikleri izleyip bağdaştırıcıya bildirimde bulunabilir.
GADMediationNativeAd
protocol İki yöntem içerir:
didRecordImpression:
ve didRecordClickOnAssetWithName:view:viewController:
özel etkinliklerin uyumlulaştırılmış yerel reklam nesnesinde ilgili yöntemi çağırmak için uygulayabileceği:
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]; } }
Protokolü uygulayan sınıf, GADMediationNativeAd
protocol
Örnek SDK'nın yerel reklam nesnesine bir referans içerdiğinden, bir tıklamayı veya gösterimi bildirmek için söz konusu nesnede uygun yöntemi çağırabilir.didRecordClickOnAssetWithName:view:viewController:
yönteminin tek bir parametre aldığını unutmayın: tıklamayı alan yerel reklam öğesine karşılık gelen View
nesnesi.
Uyumlulaştırılmış SDK ile tıklamaları ve gösterimleri izleme
Bazı uyumlulaştırılmış SDK'lar, tıklamaları ve gösterimleri kendi başlarına izlemeyi tercih edebilir. Bu durumda, handlesUserClicks
ve handlesUserImpressions
yöntemlerini aşağıdaki snippet'te gösterildiği gibi uygulamanız gerekir. YES
değerini döndürerek, bu etkinliklerin izlenmesinden özel etkinliğin sorumlu olduğunu ve bu etkinlikler gerçekleştiğinde Google Mobile Ads SDK'sına bilgi verileceğini belirtmiş olursunuz.
Tıklama ve gösterim izlemeyi geçersiz kılan özel etkinlikler, uyumlulaştırılmış SDK'nın gerçek izlemeyi yapmasını sağlamak amacıyla yerel reklamın görünümünü uyumlulaştırılmış SDK'nın yerel reklam nesnesine iletmek için didRenderInView:
mesajını kullanabilir. Özel etkinlik örneği projemizdeki örnek SDK (bu kılavuzun kod snippet'lerinin alındığı) bu yaklaşımı kullanmıyor' ancak varsa özel etkinlik kodu, aşağıdaki snippet'te gösterildiği gibi setNativeAdView:view:
yöntemini çağırır:
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]; }
Uyumlulaştırma etkinliklerini Google Mobile Ads SDK'sına yönlendirme
Yüklenmiş bir reklamla GADMediationNativeLoadCompletionHandler
çağrıldıktan sonra, döndürülen GADMediationNativeAdEventDelegate
yetki nesnesi, daha sonra bağdaştırıcı tarafından, sunu etkinliklerini üçüncü taraf SDK'dan Google Mobile Ads SDK'sına yönlendirmek için kullanılabilir.
Uygulamanızın Google Mobile Ads SDK'sından bu eşdeğer etkinlikleri alması için özel etkinliğinizin bu geri çağırmaları mümkün olduğunca fazla yönlendirmesi önemlidir. Geri çağırma işlevinin kullanımına ilişkin bir örneği burada bulabilirsiniz:
Böylece yerel reklamlar için özel etkinlikler uygulama işlemi tamamlanır. Tam örneği GitHub'da bulabilirsiniz.