הטמעה של מתאם למודעות מתגמלות

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

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

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

הגדרת שם המחלקה של המתאם והפרמטרים של השרת

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

לפני שאתם מפתחים מתאם גישור, עליכם לספק ל-Google את שם מחלקת המתאם ופרמטרים נדרשים אחרים כדי לקבל גישה לרשת המודעות שלכם.

התאמה לפרוטוקול GADMediationAdapter

בשלב הראשון, צריך להטמיע את מחלקת המתאם עם הפרוטוקול GADMediationAdapter:

#import <Foundation/Foundation.h>
#import <GoogleMobileAds/GoogleMobileAds.h>
#import <SampleAdSDK/SampleAdSDK.h>

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

השינוי הזה מבטיח שבכיתה שלך יוטמעו כמה שיטות שמפורטות בהמשך.

דיווח על מחלקה

אם הרשת של הצד השלישי רוצה לאפשר לבעלי אתרים להעביר פרמטרים אופציונליים נוספים לבקשת מודעה, יש להחזיר את המחלקה extras מ-method networkExtrasClass. הפונקציה מחזירה את הערך Nil אם הצד השלישי לא תומך בתוספות שסופקו על ידי בעל התוכן הדיגיטלי.

#import <GoogleMobileAds/GoogleMobileAds.h>

@interface SampleExtras : NSObject<GADAdNetworkExtras>

/// Use this to indicate if debug mode is on for logging.
@property(nonatomic) BOOL debugLogging;

/// Use this to indicate whether to mute audio for video ads.
@property(nonatomic) BOOL muteAudio;

@end

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleExtras class];
}
...
@end

מספרי הגרסאות של הדוח

המתאם חייב לדווח ל-Google Mobile Ads SDK גם על גרסת המתאם עצמו וגם על גרסת ה-SDK של הצד השלישי. הגרסאות מדווחות באמצעות GADVersionNumber.

המתאמים לגרסאות של הקוד הפתוח של Google משתמשים בסכמת גרסאות מתאמים של 4 ספרות, אבל GADVersionNumberמאפשרים רק 3 ספרות. כדי לעקוף את הבעיה, מומלץ לשלב את שתי הספרות האחרונות בגרסת התיקון, כפי שמוצג כאן:

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = SampleSDKVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 3) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    version.patchVersion = [versionComponents[2] integerValue];
  }
  return version;
}

+ (GADVersionNumber)version {
  NSString *versionString = SampleAdapterVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 4) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    // Adapter versions have 2 patch versions. Multiply the first patch by 100.
    version.patchVersion =
        [versionComponents[2] integerValue] * 100 + [versionComponents[3] integerValue];
  }
  return version;
}
...
@end

לאתחל את המתאם

כשאפליקציה מפעילה את Google Mobile Ads SDK, setUpWithConfiguration:completionHandler: מופעל בכל המתאמים שהוגדרו לאפליקציה בממשק המשתמש של AdMob.

הארגומנט GADMediationServerConfiguration מספק מידע על כל מיקומי המודעות שהוגדרו לאפליקציה בממשק המשתמש של AdMob. השתמשו במידע הזה כדי להפעיל את ה-SDK של רשת המודעות. אחרי שה-SDK של רשת המודעות מופעל, מפעילים את הארגומנט GADMediationAdapterSetUpCompletionBlock. החסימה הזו מאפשרת לדווח על אתחול מוצלח או נכשל ל-Google Mobile Ads SDK על ידי הפעלת ה-handler להשלמה באמצעות אובייקט nil או NSError.

#import "SampleAdapter.h"

@implementation SampleAdapter
...
+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  // Since the Sample SDK doesn't need to be initialized, the completion
  //handler is called directly here.
  completionHandler(nil);
}
...
@end

בקשה למודעה מתגמלת

כשאפליקציה טוענת מודעה מתגמלת באמצעות Google Mobile Ads SDK, loadRewardedAdForAdConfiguration:completionHandler: מופעל באמצעות המתאם אם רשת המודעות נמצאת ברשימת הרשתות בתהליך בחירת הרשת.

באמצעות GADRewardedLoadCompletionHandler אפשר לדווח ל-Google Mobile Ads SDK על כמות מודעות שנכשלה באמצעות הפניה לאובייקט שתואם לפרוטוקול GADMediationRewardedAd, או על כשל של טעינת מודעה באמצעות הוספת קובץ עזר nil ואובייקט NSError. הפעלת ה-handler של השלמת הטעינה מחזירה GADMediationRewardedAdEventDelegate שהמתאם צריך להחזיק בו למשך מחזור החיים של המודעה, כדי להודיע ל-Google Mobile Ads SDK על כל אירוע נוסף.

#import "SampleAdapter.h"

@interface SampleAdapter () <GADMediationRewardedAd> {
  /// Rewarded ads from Sample SDK.
  SampleRewardedAd *_rewardedAd;

  /// Handles any callback when the sample rewarded ad finishes loading.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// Delegate for receiving rewarded ad notifications.
  __weak id<GADMediationRewardedAdEventDelegate> _rewardedAdDelegate;
}
@end

@implementation SampleAdapter
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  _loadCompletionHandler = completionHandler;

  NSString *adUnit = adConfiguration.credentials.settings[SampleSDKAdUnitIDKey];
  SampleExtras *extras = adConfiguration.extras;

  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.enableDebugLogging = extras.enableDebugLogging;

  /// Check the extras to see if the request should be customized.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.mute = extras.muteAudio;

  /// Set the delegate on the rewarded ad to listen for callbacks from the Sample SDK.
  _rewardedAd.delegate = self;
  [_rewardedAd fetchAd:request];
}
...
@end

אירועי שרת ממסר של טעינת מודעות

המתאם אחראי להאזין לקריאות חוזרות של SDK של צד שלישי ולמפות אותן לקריאה החוזרת (callback) המתאימה של Google Mobile Ads SDK.

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

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:GADErrorNoFill
                                              userInfo:nil]);
}

הצגת המודעה

כשהאפליקציה מבקשת מ-Google Mobile Ads SDK להציג את המודעה המתגמלת, ה-SDK קורא ל-method presentFromViewController: במופע של GADMediationRewardedAd שצוין בקריאה ל-handler להשלמת הטעינה. בשלב הזה צריך להציג את המודעה המתגמלת:

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if (!_rewardedAd.isReady) {
    NSError *error =
        [NSError errorWithDomain:kAdapterErrorDomain
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [_rewardedAdDelegate didFailToPresentWithError:error];
    return;
  }
  [_rewardedAd presentFromRootViewController:viewController];
}

דיווח על אירועי מודעות ל-Mobile Ads SDK

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

- (void)rewardedAdDidPresent:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willPresentFullScreenView];
  [_rewardedAdDelegate didStartVideo];
  [_rewardedAdDelegate reportImpression];
}

- (void)rewardedAdDidDismiss:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willDismissFullScreenView];
  [_rewardedAdDelegate didEndVideo];
  [_rewardedAdDelegate didDismissFullScreenView];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@"GADMediationAdapterSampleAdNetwork"
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [_rewardedAdDelegate didRewardUserWithReward:aReward];
}

בהמשך מופיעים אירועי המודעות שמדווחים ל-Google Mobile Ads SDK:

אירוע מודעה	התיאור
willPresentFullScreenView	מודיע ל-Google Mobile Ads SDK שהמודעה תוצג.
didStartVideo	מודיע ל-Google Mobile Ads SDK שמודעה מתגמלת התחילה לפעול.
reportImpression	מודיע ל-Google Mobile Ads SDK שהתקבלה חשיפה במודעה.
didEndVideo	מודיע ל-Google Mobile Ads SDK שהמודעה המתגמלת הסתיימה.
didRewardUserWithReward	תודיע ל-Google Mobile Ads SDK שהמשתמש הרוויח תגמול.
reportClick	מודיע ל-Google Mobile Ads SDK שבוצע קליק על המודעה.
willDismissFullScreenView	מודיע ל-Google Mobile Ads SDK שהמודעה תיסגר.
didDismissFullScreenView	מודיע ל-Google Mobile Ads SDK שהמודעה נסגרה.