אירועים בהתאמה אישית של מודעות מתגמלות

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

משלימים את הגדרת האירועים המותאמים אישית.

שליחת בקשה להצגת מודעה מתגמלת

כשמגיעים לפריט מותאם אישית של אירוע בשרשרת ה-Waterfall לבחירת רשת, מתבצעת קריאה לשיטה loadRewarded:adConfiguration:completionHandler: בשם המחלקה שציינתם כשיצרתם אירוע מותאם אישית. במקרה הזה, ה-method נמצא ב-SampleCustomEvent, שקורא ל-method‏ loadRewarded:adConfiguration:completionHandler: ב-SampleCustomEventRewarded.

כדי לבקש מודעה מתגמלת, צריך ליצור או לשנות מחלקה שמטמיעה את המחלקות GADMediationAdapter ו-loadRewarded:adConfiguration:completionHandler:. אם כבר קיימת מחלקה שמרחיבה את GADMediationAdapter, צריך להטמיע את loadRewarded:adConfiguration:completionHandler: שם. בנוסף, צריך ליצור מחלקה חדשה כדי להטמיע את GADMediationRewardedAd.

בדוגמה של האירוע המותאם אישית, SampleCustomEvent מטמיע את הממשק GADMediationAdapter ואז מעביר את ההרשאה ל-SampleCustomEventRewarded.

Swift

import GoogleMobileAds

class SampleCustomEvent: NSObject, MediationAdapter {

  fileprivate var rewardedAd: SampleCustomEventRewarded?
  ...

  func loadRewarded(
    for adConfiguration: MediationRewardedAdConfiguration,
    completionHandler: @escaping GADMediationRewardedLoadCompletionHandler
  ) {
    self.rewardedAd = SampleCustomEventRewarded()
    self.rewardedAd?.loadRewarded(
      for: adConfiguration, completionHandler: completionHandler)
  }
}

Objective-C

#import "SampleCustomEvent.h"

@implementation SampleCustomEvent
...

SampleCustomEventRewarded *sampleRewarded;

- (void)loadRewardedForAdConfiguration:
            (GADMediationRewardedAdConfiguration *)adConfiguration
                     completionHandler:
                         (GADMediationRewardedLoadCompletionHandler)
                             completionHandler {
  sampleRewarded = [[SampleCustomEventRewarded alloc] init];
  [sampleRewarded loadRewardedForAdConfiguration:adConfiguration
                               completionHandler:completionHandler];
}

SampleCustomEventRewarded אחראי למשימות הבאות:

  • טעינת המודעה המתגמלת.

  • הטמעה של פרוטוקול GADMediationRewardedAd.

  • קבלת נתונים של קריאות חוזרות (callback) של אירועים שקשורים למודעות ודיווח עליהם אל Google Mobile Ads SDK.

הפרמטר האופציונלי שהוגדר בממשק המשתמש של Ad Manager נכלל בהגדרת המודעה. אפשר לגשת לפרמטר דרך adConfiguration.credentials.settings[@"parameter"]. הפרמטר הזה הוא בדרך כלל מזהה של יחידת מודעות שנדרש על ידי SDK של רשת מודעות כשיוצרים מופע של אובייקט מודעה.

Swift

class SampleCustomEventRewarded: NSObject, MediationRewardedAd {
  /// The Sample Ad Network rewarded ad.
  var nativeAd: SampleRewarded?

  /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
  var delegate: MediationRewardedAdEventDelegate?

  /// Completion handler called after ad load.
  var completionHandler: GADMediationRewardedLoadCompletionHandler?

  func loadRewarded(
    for adConfiguration: MediationRewardedAdConfiguration,
    completionHandler: @escaping GADMediationRewardedLoadCompletionHandler
  ) {
    rewarded = SampleRewarded.init(
      adUnitID: adConfiguration.credentials.settings["parameter"] as? String)
    rewarded?.delegate = self
    let adRequest = SampleAdRequest()
    adRequest.testMode = adConfiguration.isTestRequest
    self.completionHandler = completionHandler
    rewarded?.fetchAd(adRequest)
  }
}

Objective-C

#import "SampleCustomEventRewarded.h"

@interface SampleCustomEventRewarded () <SampleRewardedAdDelegate,
                                         GADMediationRewardedAd> {
  /// The sample rewarded ad.
  SampleRewarded *_rewardedAd;

  /// The completion handler to call when the ad loading succeeds or fails.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// The ad event delegate to forward ad rendering events to Google Mobile Ads SDK.
  id <GADMediationRewardedAdEventDelegate> _adEventDelegate;
}
@end

- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
  __block GADMediationRewardedLoadCompletionHandler originalCompletionHandler =
      [completionHandler copy];

  _loadCompletionHandler = ^id<GADMediationRewardedAdEventDelegate>(
      _Nullable id<GADMediationRewardedAd> ad, NSError *_Nullable error) {
    // Only allow completion handler to be called once.
    if (atomic_flag_test_and_set(&completionHandlerCalled)) {
      return nil;
    }

    id<GADMediationRewardedAdEventDelegate> 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;
  };

  NSString *adUnit = adConfiguration.credentials.settings[@"parameter"];
  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.delegate = self;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = adConfiguration.isTestRequest;
  [_rewardedAd fetchAd:adRequest];
}

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

בדרך כלל, השיטות האלה מוטמעות בתוך קריאות חוזרות (callbacks) מ-SDK של צד שלישי שהמתאם מטמיע. בדוגמה הזו, ל-Sample SDK יש SampleRewardedAdDelegate עם קריאות חוזרות רלוונטיות:

Swift

func rewardedDidLoad(_ interstitial: SampleRewarded) {
  if let handler = completionHandler {
    delegate = handler(self, nil)
  }
}

func rewarded(
  rewarded: SampleRewarded, didFailToLoadAdWith errorCode: SampleErrorCode
) {
  let error =
    SampleCustomEventUtils.SampleCustomEventErrorWithCodeAndDescription(
      code: SampleCustomEventErrorCode
        .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)rewardedDidLoad:(SampleRewarded *)rewarded {
  _adEventDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewarded:(SampleInterstitial *)rewarded
    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);
}

כדי להשתמש ב-GADMediationrewardedAd, צריך להטמיע שיטה להצגת המודעה: present(viewController:)

Swift

func present(from viewController: UIViewController) {
  if let rewarded = rewarded, rewarded.isRewardedLoaded {
    rewarded.show()
  }
}

Objective-C

- (void)presentFromViewController:(UIViewController *)viewController {
  if ([_rewardedAd isRewardedLoaded]) {
    [_rewardedAd show];
  } else {
    NSError *error = SampleCustomEventErrorWithCodeAndDescription(
        SampleCustomEventErrorAdNotLoaded,
        [NSString stringWithFormat:
                      @"The rewarded ad failed to present because the ad was not loaded."]);
    [_adEventDelegate didFailToPresentWithError:error]
  }
}

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

אחרי שמפעילים את GADMediationRewardedLoadCompletionHandler עם מודעה טעונה, אפשר להשתמש באובייקט הנציג GADMediationRewardedAdEventDelegate שמוחזר על ידי המתאם כדי להעביר אירועי הצגה מ-SDK של צד שלישי אל Google Mobile Ads SDK. המחלקות SampleCustomEventRewarded ו-SampleCustomEventRewarded מטמיעות את הפרוטוקול SampleRewardedAdDelegate כדי להעביר קריאות חוזרות מרשת המודעות לדוגמה אל Google Mobile Ads SDK.

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

Swift

func rewardedAdDidPresent(_ rewarded: SampleRewardedAd) {
  delegate?.willPresentFullScreenVideo()
  delegate?.didStartVideo()
}

func rewardedAdUserDidEarnReward(_ rewarded: SampleRewardedAd) {
  AdReward aReward = AdReward("", rewarded)
  delegate.didRewardUser()
}

Objective-C

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

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

כך מסיימים את ההטמעה של אירועים מותאמים אישית במודעות מתגמלות. הדוגמה המלאה זמינה ב-GitHub. אפשר להשתמש בו עם רשת מודעות שכבר נתמכת, או לשנות אותו כדי להציג מודעות מתגמלות עם אירועים בהתאמה אישית.