דרישות מוקדמות
משלימים את הגדרת האירועים בהתאמה אישית.
בקשה למודעה מותאמת
כשמגיעים לפריט של האירוע המותאם אישית בשרשרת של רשימת הרשתות בתהליך בחירת הרשת,
קוראים ל-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, 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
.קבלת קריאות חוזרות (callback) של אירועי מודעה ודיווח עליהן ל-Google Mobile Ads SDK
הפרמטר האופציונלי שמוגדר בממשק המשתמש של Ad Manager הוא
שכלולות בהגדרת המודעה.
אפשר לגשת לפרמטר דרך
adConfiguration.credentials.settings[@"parameter"]
הפרמטר הזה
בדרך כלל מזהה יחידת מודעות שנדרש ל-SDK של רשת מודעות,
יצירת אובייקט של מודעה.
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
עבור פרמטר השגיאה; במקרה של כשל, מעבירים את השגיאה
המערכת נתקלה בבעיה.
בדרך כלל, השיטות האלה מוטמעות בתוך קריאות חוזרות (callbacks)
ה-SDK של הצד השלישי שהמתאם מטמיע. לצורך הדוגמה הזו, ערכת ה-SDK לדוגמה
כולל SampleNativeAdDelegate
עם קריאה חוזרת (callback) רלוונטית:
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 בתהליך בחירת הרשת (Mediation), צריך להשתמש במחלקה שמטמיעה את GADMediationNativeAd
,
למשל SampleCustomEventNativeAd
, ל"מפה" אובייקט המודעה המותאמת של ה-SDK בתהליך בחירת הרשת (Mediation)
ולכן הוא תואם לממשק שנדרש על ידי 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
כולל method
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 = [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
כולל שתי שיטות: 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
הפרוטוקול מכיל הפניה לאובייקט של המודעה המותאמת לדוגמה של Sample SDK, והוא יכול לקרוא
המתאימה לאובייקט הזה לדיווח על קליק או חשיפה. שימו לב
השיטה didRecordClickOnAssetWithName:view:viewController:
נדרשת פעם אחת
הפרמטר: האובייקט View
שתואם לנכס המודעה המותאם שהתקבל
הקליק.
מעקב אחרי קליקים וחשיפות באמצעות ה-SDK בתהליך בחירת הרשת (Mediation)
יכול להיות שחלק מערכות ה-SDK שמשתתפות בתהליך בחירת הרשת יעדיפו לעקוב אחרי קליקים וחשיפות בעצמם. לחשבון
במקרה כזה, צריך להטמיע את handlesUserClicks
handlesUserImpressions
methods, כמו שמוצג בקטע הקוד שבהמשך. על ידי חזרה
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]; }
העברת אירועי תהליך בחירת הרשת (Mediation) אל Google Mobile Ads SDK
אחרי שמתקשרים
GADMediationNativeLoadCompletionHandler
עם מודעה שנטענה, נציג GADMediationNativeAdEventDelegate
הוחזר
לאחר מכן יכול להשתמש במתאם כדי להעביר אירועי מצגת
SDK של צד שלישי ל-Google Mobile Ads SDK.
חשוב שהאירוע בהתאמה אישית יעביר כמה שיותר מהקריאות החוזרות האלה כדי שהאפליקציה שלך תקבל את האירועים המקבילים האלה Mobile Ads SDK. דוגמה לשימוש בקריאות חוזרות (callback):
הושלמה ההטמעה של אירועים מותאמים אישית במודעות מותאמות. הדוגמה המלאה זמין ב- GitHub.