דרישות מוקדמות
משלימים את הגדרת האירועים המותאמים אישית.
בקשה להצגת מודעה מותאמת
כשהפריט של האירוע בהתאמה אישית מגיע לשרשרת לבחירת רשת (Mediation) ב-Waterfall, מתבצעת קריאה ל-method loadNativeAd:adConfiguration:completionHandler: בשם המחלקה שציינתם כשיצרתם אירוע בהתאמה אישית. במקרה הזה, ה-method הזו נמצאת ב-SampleCustomEvent, שקוראת ל-method 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) } }
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.קבלת קריאות חוזרות (callback) של אירועי מודעות ודיווח עליהן אל Google Mobile Ads SDK.
הפרמטר האופציונלי שמוגדר בממשק המשתמש של AdMob נכלל בהגדרת המודעה.
אפשר לגשת לפרמטר דרך adConfiguration.credentials.settings[@"parameter"]. הפרמטר הזה הוא בדרך כלל מזהה של יחידת מודעות שנדרש ל-SDK של רשת המודעות כשיוצרים מופע של אובייקט מודעה.
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]; }
בין אם המודעה אוחזרה בהצלחה ובין אם אירעה שגיאה, צריך להפעיל את GADMediationNativeAdLoadCompletionHandler. אם הפעולה הצליחה, מעבירים את המחלקה שמיישמת את GADMediationNativeAd עם ערך nil לפרמטר השגיאה. אם הפעולה נכשלה, מעבירים את השגיאה שנתקלתם בה.
בדרך כלל, השיטות האלה מוטמעות בתוך קריאות חוזרות (callbacks) מ-SDK של צד שלישי שהמתאם שלכם מטמיע. בדוגמה הזו, ל-Sample SDK יש SampleNativeAdDelegate עם קריאות חוזרות (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); }
מודעות מותאמות במפות Google
לערכות 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: [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; }
רשתות מסוימות שמשתתפות בתהליך בחירת הרשת יכולות לספק נכסים נוספים מעבר לאלה שמוגדרים על ידי Google Mobile Ads SDK. הפרוטוקול GADMediationNativeAd כולל שיטה שנקראת extraAssets, שבה Google Mobile Ads SDK משתמש כדי לאחזר את הנכסים "הנוספים" האלה מהממפה.
נכסי תמונות של מפות
מיפוי של נכסי תמונות מורכב יותר ממיפוי של סוגי נתונים פשוטים יותר, כמו NSString או double. יכול להיות שהתמונות יורדו באופן אוטומטי או יוחזרו כערכי כתובות URL. גם צפיפות הפיקסלים שלהם יכולה להשתנות.
כדי לעזור לכם לנהל את הפרטים האלה, 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)] }
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 כולל שתי שיטות: 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 מכילה הפניה לאובייקט המודעה המותאמת של ה-SDK לדוגמה, היא יכולה להפעיל את השיטה המתאימה באובייקט הזה כדי לדווח על קליק או חשיפה. שימו לב שהשיטה didRecordClickOnAssetWithName:view:viewController: מקבלת פרמטר אחד: האובייקט View שתואם לנכס שמצורף למודעה של מודעה מותאמת שקיבל את הקליק.
מעקב אחרי קליקים וחשיפות באמצעות ה-SDK של רשת המודעות המתווכת
יכול להיות שערכות SDK מסוימות שמשתתפות בתהליך בחירת הרשת יעדיפו לעקוב אחרי קליקים וחשיפות בעצמן. במקרה כזה, צריך להטמיע את השיטות handlesUserClicks ו-handlesUserImpressions, כמו שמוצג בקטע הקוד שבהמשך. החזרת הערך YES מציינת שהאירוע בהתאמה אישית אחראי למעקב אחרי האירועים האלה, ויודיע ל-Google Mobile Ads SDK כשהאירועים האלה יתרחשו.
אירועים מותאמים אישית שמבטלים את המעקב אחרי קליקים ומעקב חשיפות יכולים להשתמש בהודעה didRenderInView: כדי להעביר את התצוגה של המודעה המותאמת לאובייקט המודעה המותאמת של ה-SDK המתווך, כדי לאפשר ל-SDK המתווך לבצע את המעקב בפועל. בפרויקט לדוגמה של אירוע בהתאמה אישית (שממנו נלקחו קטעי הקוד במדריך הזה), ערכת ה-SDK לדוגמה לא משתמשת בגישה הזו. אבל אם היא הייתה משתמשת בה, הקוד של האירוע בהתאמה אישית היה קורא ל-method 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]; }
העברת אירועים של תהליך בחירת הרשת (Mediation) אל Google Mobile Ads SDK
אחרי שקוראים ל-GADMediationNativeLoadCompletionHandler עם מודעה שנטענה, המתאם יכול להשתמש באובייקט הנציג GADMediationNativeAdEventDelegate שמוחזר כדי להעביר אירועי הצגה מ-SDK של הצד השלישי אל Google Mobile Ads SDK.
חשוב שהאירוע בהתאמה אישית יעביר כמה שיותר מהקריאות החוזרות האלה, כדי שהאפליקציה תקבל את האירועים המקבילים האלה מ-Google Mobile Ads SDK. דוגמה לשימוש בקריאות חוזרות (callbacks):
בשלב הזה מסתיימת ההטמעה של אירועים מותאמים אישית במודעות מותאמות. הדוגמה המלאה זמינה ב-GitHub.