פיתוח מתאם מנגנון בחירת הרשת למודעות

הערה: השימוש שלך ב-Google Mobile Ads SDK בהקשר של שירותי הגישור כפוף לתנאים ולהגבלות של תהליך בחירת הרשת.

המדריך הזה מיועד לרשתות מודעות שמעוניינות לבנות מתאם לתהליך בחירת הרשת (Mediation). אם אתם בעלי תוכן דיגיטלי, קראו את ההוראות לתהליך בחירת הרשת לבעלי אפליקציות.

מתאם גישור הוא שכבת התקשורת בין רשת המודעות שלך לבין 'גישור מודעות Google לנייד'. מתאמים מציגים מודעות מרשת המודעות שלכם ומעבירים אירועי מודעות רלוונטיים אל AdMob. המתאם אחראי להטמעה של הפרוטוקול GADMAdNetworkAdapter כדי לוודא שהוא מספק את היכולות הנדרשות.

דרישות מוקדמות

• Xcode 15.3 ואילך
• יעד פריסה של 8.0 ומעלה
• כותרות נוספות מהתיקייה Mediation Adapters (מתאמי גישור) בהורדה של Google Mobile Ads iOS SDK

לרשת המודעות שלכם צריכה להיות קשרי עבודה ברורים עם Google כדי ליצור מתאם גישור.

רשת מודעות לדוגמה

במדריך הזה נסביר איך לבנות מתאם לרשת המודעות לדוגמה. ה-SDK של רשת המודעות לדוגמה מכיל מחלקות שמייצגות את המחלקות המוצעות על ידי רוב רשתות המודעות:

@interface SampleBanner : UILabel

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleBannerAdDelegate> delegate;
- (void)fetchAd:(SampleAdRequest *)request;

@end

typedef NS_ENUM(NSInteger, SampleErrorCode) {
  SampleErrorCodeBadRequest = 0,
  SampleErrorCodeUnknown = 1,
  SampleErrorCodeNetworkError = 2,
  SampleErrorCodeNoInventory = 3,
};

@interface SampleAdRequest : NSObject

@property(nonatomic, assign) BOOL testMode;
@property(nonatomic, copy) NSArray *keywords;

@end

@interface SampleInterstitial : NSObject

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleInterstitialAdDelegate> delegate;
@property(nonatomic, assign, getter=isInterstitialLoaded) BOOL interstitialLoaded;
- (void)fetchAd:(SampleAdRequest *)request;
- (void)show;

@end

@protocol SampleBannerAdDelegate
- (void)bannerDidLoad:(SampleBanner *)banner;
- (void)banner:(SampleBanner *)banner didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)bannerWillLeaveApplication:(SampleBanner *)banner;

@end

@protocol SampleInterstitialAdDelegate<NSObject>
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial;
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial;

@end

כדי לקבל מידע נוסף על המחלקות האלה, תוכלו לעיין בדוגמה המלאה של הטמעת SDK.

ספק הנתונים של החיבור

מתאמים לתהליך בחירת הרשת (Mediation) יוצרים אינטראקציה עם Google Mobile Ads SDK באמצעות אובייקט שמטמיע את הפרוטוקול GADMAdNetworkConnector. מכאן ואילך, נקרא לאובייקט הזה המחבר. המחבר חושף את המידע הנדרש לבקשות להצגת מודעות ומספק אמצעי להתקשרות חזרה לגישור במקרה של אירועי מודעות ואינטראקציות של משתמשים. המחבר מסופק למתאמים של תהליך בחירת הרשת (Mediation) בזמן האתחול. מגדירים את המתאם כך שיאחסן את המחבר במשתנה של מכונה:

- (id)initWithGADMAdNetworkConnector:(id<GADMAdNetworkConnector>)c {
  if ((self = [super init])) {
    _connector = c;
  }
  return self;
}

פרמטרים של שרת

סביר להניח שרשת המודעות שלכם זקוקה למזהים כדי לזהות את בעל התוכן הדיגיטלי. לדוגמה, ברשת המודעות לדוגמה נדרשת יחידת מודעות. הפרמטרים הנדרשים האלה של השרת מסופקים למתאם באמצעות השיטה credentials, שמחזירה מזהה NSDictionary וערכים תואמים. שורת הקוד הבאה מאחזרת את פרמטר השרת בשם ad_unit עבור רשת המודעות לדוגמה מהמחבר:

self.interstitialAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

הגדרת רשת של תהליך בחירת הרשת (Mediation)

רשתות המודעות צריכות ליידע את AdMob מהם הפרמטרים הנדרשים של השרת עבור הרשת שלהן. כך מערכת AdMob יכולה להגדיר את הרשת בממשק הקצה.

כשמפעילים את הרשת לגישור בממשק הקצה, מערכת AdMob דורשת להזין את הערכים הדרושים ליצירת המתאם. בצילום המסך הבא צריך לציין מזהה מיקום של אפליקציה (APID) בשביל מילניום מדיה ומזהה אפליקציה נדרש ב-InMobi.

קראו את המאמר הזה כדי לקבל מידע נוסף על הגדרת רשתות מודעות של גישור.

שליחת בקשה להצגת מודעה בתהליך בחירת הרשת (Mediation)

בקשה להצגת מודעת באנר

בבקשות לבאנר של גישור, השיטה getBannerWithSize נקראת מיד אחרי יצירת המתאם. השיטה הזו לא מחזירה שום דבר. הוא מסמן למתאם להתחיל אחזור מודעה אסינכרוני ברשת. יש להגדיר שהמתאם יאזין לקריאות חוזרות (callback) עבור ה-SDK. אם ה-SDK לא תומך בגודל המודעה הנתון או לא תומך במודעות באנר, צריך להפעיל את השיטה adapter:didFailAd: במחבר.

יישום של getBannerWithSize עבור רשת המודעות לדוגמה נראה כך:

- (void)getBannerWithSize:(GADAdSize)adSize {
  //The adapter should fail immediately if the adSize is not supported
  if (!GADAdSizeEqualToSize(adSize, GADAdSizeBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeMediumRectangle) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeFullBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeLeaderboard)) {
    NSString *errorDesc =
        [NSString stringWithFormat:@"Invalid ad type %@, not going to get ad.",
                                   NSStringFromGADAdSize(adSize)];
    NSDictionary *errorInfo = [NSDictionary
        dictionaryWithObjectsAndKeys:errorDesc, NSLocalizedDescriptionKey, nil];
    NSError *error = [NSError errorWithDomain:GADErrorDomain
                                         code:GADErrorMediationInvalidAdSize
                                     userInfo:errorInfo];
    [self.connector adapter:self didFailAd:error];
    return;
  }
  self.bannerAd = [[SampleBanner alloc]
      initWithFrame:CGRectMake(0, 0, adSize.size.width, adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

  // Setup request parameters.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;
  [self.bannerAd fetchAd:request];
  NSLog(@"Requesting banner from Sample Ad Network");
}

פרמטרים נוספים של טירגוט

המחבר מכיל מידע נפוץ על מיקוד, שתוכל לעיין בו לצורך מיקוד מודעות:

• userKeywords
• testMode
• childDirectedTreatment

תוספות לגישור

תוספות לגישור מאפשרות לרשת המודעות לתמוך בפרמטרים נוספים של מיקוד או בקלט, שאינם מכוסים על ידי הפרמטרים הנוספים של הבקשה שהמחבר מספק. אפשר לתת את הפונקציונליות הזו באמצעות מחלקה שמטמיעה את הפרוטוקול GADAdNetworkExtras. המחלקה SampleAdNetworkExtras מוצגת למטה כדוגמה:

@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// Should ad volume audio be muted.
@property(nonatomic, assign) BOOL muteAudio;

@end

בעלי תוכן דיגיטלי חייבים להעביר מופע של מחלקת המשנה GADAdNetworkExtras כשהם שולחים בקשה להצגת מודעה. ניתן לגשת למופע הזה של מחלקת המשנה GADAdNetworkExtras דרך המחבר. כך תוכלו להשתמש בתוספות לגישור במהלך בניית בקשה להצגת מודעה עבור הרשת שלכם:

SampleAdRequest *request = [[SampleAdRequest alloc] init];
SampleAdNetworkExtras *myAdNetworkExtras = [self.connector networkExtras];
request.muteAudio = myAdNetworkExtras.muteAudio;
[self.bannerAd fetchAd:request];

כדי להבטיח שניתן לגשת למחלקה המשנית של GADAdNetworkExtras דרך המחבר, מטמיעים את networkExtrasClass ומחזירים את מחלקת המשנה GADAdNetworkExtras:

+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleAdNetworkExtras class];
}

אם המתאם לא משתמש בתוספות לתהליך בחירת הרשת, השיטה networkExtrasClass מחזירה Nil.

שליחת הודעה לתהליך בחירת הרשת (Mediation)

בקשו מהמתאם להטמיע את ה-listener ברשת שלכם ולהעביר את הקריאות החוזרות (callback) הרלוונטיות של אירועי המודעה דרך המחבר. בטבלה הבאה מוסבר מתי צריך לקרוא לכל שיטת הענקת גישה:

שיטה	מתי להתקשר
adapter:didReceiveAdView:	בקשת הבאנר בוצעה בהצלחה.
adapter:didFailAd:	בקשת הבאנר נכשלה.
adapterDidGetAdClick:	בוצעה לחיצה על הבאנר.
adapterWillPresentFullScreenModal:	הבאנר יציג שכבת-על בתוך האפליקציה.
adapterWillDismissFullScreenModal:	שכבת-העל בתוך האפליקציה תיסגר.
adapterDidDismissFullScreenModal:	שכבת-העל בתוך האפליקציה נסגרה.
adapterWillLeaveApplication:	האפליקציה תמוקם ברקע או תסתיים בעקבות לחיצה של המשתמש על מודעה שתפעיל אפליקציה אחרת.

הדוגמה הבאה מטמיעה את הממשק SampleBannerAdDelegate מרשת המודעות לדוגמה, כדי להעביר הודעות שגיאה וסטטוס:

- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.connector adapter:self didReceiveAdView:banner];
}

- (void)banner:(SampleBanner *)banner didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
                didFailAd:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.connector adapterDidGetAdClick:self];
  [self.connector adapterWillLeaveApplication:self];
}

הפעלה של שכבת-על בתוך האפליקציה לעומת אפליקציה חיצונית

כשמשתמש לוחץ על באנר, המודעה עשויה לפתוח שכבת-על במסך מלא או אפליקציה חיצונית (כמו Safari או חנות האפליקציות). הקריאות החוזרות של המחבר להפעלה בשני המקרים האלה הן שונות.

אם לחיצה על מודעת באנר פותחת שכבת-על במסך מלא, צריך להפעיל את הפקודה adapterWillPresentFullScreenModal: כשמציגים את שכבת-העל. כששכבת-העל נסגרת, מפעילים גם את adapterWillDismissFullScreenModal: וגם את adapterDidDismissFullScreenModal:.

אם קליק על באנר (או קליק על שכבת-על במסך מלא) גורם למשתמש לעזוב את האפליקציה, צריך להפעיל את הקריאה החוזרת (callback) adapterWillLeaveApplication:.

עכשיו יש לך מתאם פעיל לתהליך בחירת הרשת (Mediation) במודעות באנר. דוגמה להטמעה מלאה של SampleAdapter אפשר למצוא ב-GitHub.

הטמעת מתאם של מודעות מעברון

ההטמעה של המתאם למודעות מעברון דומה לאופן ההטמעה של מודעות באנר. מפעילים את השיטה getInterstitial מיד אחרי יצירת המתאם. השיטה הזו לא מחזירה דבר. המתאם צפוי להפעיל אחזור מודעה אסינכרוני ברשת. עליכם להגדיר את המתאם בתור הענקת גישה ל-SDK לצורך האזנה לקריאות חוזרות (callback). אם ערכת ה-SDK שלך לא תומכת במודעות מעברון, צריך להפעיל את השיטה adapter:didFailAd: במחבר באופן הבא:

- (void)getInterstitial {
  self.interstitialAd = [[SampleInterstitial alloc] init];
  self.interstitialAd.delegate = self;
  self.interstitialAd.adUnit =
      [[self.connector credentials] objectForKey:@"ad_unit"];

  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  // Setup request parameters.
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;

  [self.interstitialAd fetchAd:request];
  NSLog(@"Requesting interstitial from Sample Ad Network");
}

בדיוק כמו ב-MediationBannerAdapter, ניתן לקבל מהמחבר מידע על זיהוי בעלי תוכן דיגיטלי ועל מיקוד מודעות.

שליחת הודעה לתהליך בחירת הרשת (Mediation)

צריך לבקש מהמתאם להטמיע את ההרשאה להאצלת מודעות ברשת שלך ולהעביר את הקריאות החוזרות (callback) הרלוונטיות לאירועי המודעה דרך המחבר. בטבלה הבאה מוסבר מתי צריך לקרוא לכל שיטת הענקת גישה:

שיטה	מתי להתקשר
adapterDidReceiveInterstitial:	בקשת המעברון הצליחה.
adapter:didFailInterstitial:	בקשת המעברון נכשלה.
adapterDidGetAdClick:	בוצעה לחיצה על מודעת המעברון.
adapterWillPresentInterstitial:	המעברון יוצג.
adapterWillDismissInterstitial:	מודעת המעברון עומדת להיסגר.
adapterDidDismissInterstitial:	מודעת המעברון נסגרה.
adapterWillLeaveApplication:	האפליקציה תפעל ברקע או תסתיים כי המשתמש לחץ על מודעה שתפעיל אפליקציה אחרת.

הדוגמה הבאה מטמיעה את הממשק SampleInterstitialAdDelegate של רשת המודעות לדוגמה, כדי להעביר הודעות שגיאה וסטטוס:

- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.connector adapterDidReceiveInterstitial:self];
}

- (void)interstitial:(SampleInterstitial *)interstitial
    didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
      didFailInterstitial:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillPresentInterstitial:self];
}

- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillDismissInterstitial:self];
}

- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterDidDismissInterstitial:self];
}

להציג מודעת מעברון

אחרי שהמתאם מבצע קריאה ל-adapterDidReceiveInterstitial, צריך להמתין להצגת מודעת המעברון עד שתתבצע קריאה ל-presentInterstitialFromRootViewController. מפתח האפליקציה מחליט מתי להציג את מודעת המעברון, תהליך יכול להימשך כמה דקות אחרי שהיא מתקבלת.

הנה יישום של presentInterstitialFromRootViewController: עבור רשת המודעות לדוגמה:

- (void)presentInterstitialFromRootViewController:
    (UIViewController *)rootViewController {
  if ([self.interstitialAd isLoaded]) {
    [self.interstitialAd show];
  }
}

המתאם לתהליך בחירת הרשת מוכן לטיפול במודעות מעברון. דוגמה: אפשר למצוא הטמעה מלאה של SampleAdapter ב-GitHub.

שאלות נפוצות

צריך לכלול את המתאם כחלק מספריית ה-SDK או כספרייה נפרדת?

מומלץ לכלול את המתאם בספריית ה-SDK, כדי שהמפתחים יצטרכו להפנות רק לספרייה אחת כדי לשלב את הרשת.

מה אפשר לעשות אם המתאם שלי תומך רק במודעות באנר?

אם המתאם תומך רק במודעות באנר, צריך להעביר אירוע שגיאה לתהליך בחירת הרשת (Mediation) בבקשות מעברון:

- (void)getInterstitial {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error = [NSError errorWithDomain:GADErrorDomain
                                       code:GADErrorInvalidRequest
                                   userInfo:errorInfo];
  [self.connector adapter:self didFailInterstitial:error];
  return;
}

מה אפשר לעשות אם המתאם שלי תומך רק במודעות מעברון?

אם המתאם תומך רק במודעות מעברון, יש להעביר אירוע שגיאה לגישור בבקשות למודעות באנר:

- (void)getBannerWithSize:(GADAdSize)adSize {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error =
      [NSError errorWithDomain:GADErrorDomain
                          code:GADErrorInvalidRequest
                      userInfo:errorInfo];
  [self.connector adapter:self didFailAd:error];
  return;
}