پیشنیازها
راهاندازی رویدادهای سفارشی را تکمیل کنید.
درخواست آگهی بومی
وقتی مورد خط رویداد سفارشی در زنجیره میانجیگری آبشاری فراخوانی میشود،
روش loadNativeAd:adConfiguration:completionHandler: در نام کلاس ارائهشده هنگام ایجاد رویداد
سفارشی فراخوانی میشود. در این مورد،
این روش در SampleCustomEvent است که سپس
روش loadNativeAd:adConfiguration:completionHandler: را در
SampleCustomEventNative فرا میخواند.
برای درخواست آگهی بومی، کلاسی ایجاد یا اصلاح کنید که
GADMediationAdapter و loadNativeAd:adConfiguration:completionHandler: را پیادهسازی کند. اگر
کلاسی که GADMediationAdapter را گسترش میدهد ازقبل وجود دارد،
loadNativeAd:adConfiguration:completionHandler: را در آنجا پیادهسازی کنید. علاوهبراین، کلاس جدیدی برای پیادهسازی GADMediationNativeAd ایجاد کنید.
در مثال رویداد سفارشی ما،
SampleCustomEvent رابط
GADMediationAdapter را پیادهسازی میکند و سپس به
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) } }
آبجکتیو-سی
#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.درحال دریافت و گزارش کردن برگشتیهای رویداد آگهی به Google Mobile Ads SDK.
پارامتر اختیاری تعریفشده در «میانای کاربری AdMob»
در پیکربندی آگهی گنجانده شده است.
ازطریق
adConfiguration.credentials.settings[@"parameter"] میتوان به این پارامتر دسترسی پیدا کرد. این پارامتر معمولاً شناسه واحد آگهی است که کیت توسعه نرمافزار شبکه آگهی هنگام نمونهسازی کردن شیء آگهی به آن نیاز دارد.
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) } }
آبجکتیو-سی
#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]; }
چه آگهی باموفقیت واکشی شود چه با خطا مواجه شود، GADMediationNativeAdLoadCompletionHandler را فراخوانی میکنید. درصورت موفقیت،
کلاسی را که GADMediationNativeAd را با مقدار nil
برای پارامتر خطا پیادهسازی میکند ارسال کنید؛ درصورت عدم موفقیت، خطایی را که
با آن مواجه شدهاید ارسال کنید.
معمولاً این روشها در داخل برگشت تماس از کیت توسعه نرمافزار طرف سوم که آداپتور شما پیادهسازی میکند، پیادهسازی میشوند. برای این مثال، «کیت توسعه نرمافزار نمونه»
دارای SampleNativeAdDelegate با برگشتیهای مربوطه است:
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) } }
آبجکتیو-سی
- (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); }
آگهیهای بومی Maps
کیتهای توسعه نرمافزار مختلف قالبهای منحصربهفرد خود را برای آگهیهای بومی دارند. برای مثال، یکی ممکن است اشیایی را برگرداند که حاوی فیلد «عنوان» باشند، درحالیکه دیگری ممکن است «عنوان» داشته باشد. علاوهبراین، روشهای استفادهشده برای پیگیری ظهورها و پردازش کلیکها میتواند از یک کیت توسعه نرمافزار به کیت توسعه نرمافزار دیگر متفاوت باشد.
برای رفع این مشکلات، وقتی رویداد سفارشی از کیت توسعه نرمافزار واسطهگریشده خود
شیء آگهی بومی دریافت میکند، باید از کلاسی که GADMediationNativeAd را پیادهسازی میکند،
مثل SampleCustomEventNativeAd، استفاده کند تا شیء آگهی بومی کیت توسعه نرمافزار واسطهگریشده را
«نگاشت» کند تا با میانای موردانتظار Google Mobile Ads SDK مطابقت داشته باشد.
اکنون نگاهی دقیقتر به جزئیات پیادهسازی برای
SampleCustomEventNativeAd میاندازیم.
ذخیره کردن نگاشتها
انتظار میرود GADMediationNativeAd ویژگیهای خاصی را که از ویژگیهای دیگر «کیتهای توسعه نرمافزار» نگاشت شدهاند پیادهسازی کند:
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 }
آبجکتیو-سی
/// 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 = [NativeAdImage(image: image)] } else { let imageUrl = URL(fileURLWithPath: nativeAd.imageURL) images = [NativeAdImage(url: imageUrl, scale: nativeAd.imageScale)] }
آبجکتیو-سی
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 واسطهگری از ردیابی ظهورها و کلیکها بهتنهایی پشتیبانی میکند یا نه، رویدادهای سفارشی میتوانند از دو رویکرد متفاوت استفاده کنند.
پیگیری کلیکها و ظهورها با Google Mobile Ads SDK
اگر «کیت توسعه نرمافزار میانجیگریشده» ردیابی کلیک و ظهور خود را انجام نمیدهد اما
روشهایی برای ثبت کلیکها و ظهورها ارائه میدهد، Google Mobile Ads SDK میتواند
این رویدادها را ردیابی کند و به آداپتور اطلاع دهد. پروتکل GADMediationNativeAd
شامل دو روش است: didRecordImpression: و
didRecordClickOnAssetWithName:view:viewController: که رویدادهای سفارشی میتوانند
برای فراخوانی روش مربوطه در شیء آگهی بومی واسطهگریشده پیادهسازی کنند:
Swift
func didRecordImpression() { nativeAd?.recordImpression() } func didRecordClickOnAsset( withName assetName: GADUnifiedNativeAssetIdentifier, view: UIView, wController: UIViewController ) { nativeAd?.handleClick(on: view) }
آبجکتیو-سی
- (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
را پیادهسازی میکند مرجعی به شیء آگهی بومی «کیت توسعه نرمافزار نمونه» دارد، میتواند
روش مناسب را در آن شیء برای گزارش کلیک یا ظهور فراخوانی کند. توجه داشته باشید که روش
didRecordClickOnAssetWithName:view:viewController: یک پارامتر واحد میگیرد: شیء View مربوط به دارایی آگهی بومی که
کلیک را دریافت کرده است.
پیگیری کلیکها و ظهورها با «کیت توسعه نرمافزار میانجیگریشده»
برخیاز کیتهای توسعه نرمافزار واسطهگریشده ممکن است ترجیح دهند کلیکها و ظهورها را خودشان پیگیری کنند. در این
صورت، باید روشهای handlesUserClicks و
handlesUserImpressions را همانطور که در گزیده زیر نشان داده شده است پیادهسازی کنید. با برگرداندن
YES، نشان میدهید که رویداد سفارشی مسئولیت پیگیری
این رویدادها را میپذیرد و هنگام وقوع این رویدادها به Google Mobile Ads SDK اطلاع خواهد داد.
رویدادهای سفارشی که ردیابی کلیک و ظهور را ملغی میکنند میتوانند از پیام
didRenderInView: برای انتقال نمای آگهی بومی به
شیء آگهی بومی «کیت توسعه نرمافزار واسطهای» استفاده کنند تا «کیت توسعه نرمافزار واسطهای» بتواند ردیابی واقعی را انجام دهد. «کیت توسعه نرمافزار» نمونه از پروژه رویداد سفارشی ما (که گزیدههای کد این راهنما از آن گرفته شده است) از این رویکرد استفاده نمیکند، اما اگر استفاده میکرد، کد رویداد سفارشی روش 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) }
آبجکتیو-سی
- (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 دردسترس است.