الأحداث المخصّصة للإعلانات التي تضم مكافأة

المتطلبات الأساسية

أكمِل إعداد الأحداث المخصّصة.

طلب عرض إعلان مقابل مكافأة

عند الوصول إلى عنصر الحدث المخصّص في سلسلة التوسّط المتسلسلة، يتم استدعاء الطريقة loadRewarded:adConfiguration:completionHandler: على اسم الفئة الذي قدّمته عند إنشاء حدث مخصّص. في هذه الحالة، تكون الطريقة في SampleCustomEvent، والتي تستدعي بعد ذلك الطريقة 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

  • تلقّي عمليات ردّ الاتصال الخاصة بأحداث الإعلانات وإعداد تقارير عنها في حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة مستخدم AdMob ضمن إعدادات الإعلان. يمكن الوصول إلى المَعلمة من خلال 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 لمَعلمة الخطأ. وفي حال حدوث خطأ، مرِّر الخطأ الذي واجهته.

عادةً، يتم تنفيذ هذه الطرق داخل عمليات ردّ الاتصال من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية التي ينفّذها المحوّل. في هذا المثال، تحتوي حزمة تطوير البرامج (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]
  }
}

إعادة توجيه أحداث الوساطة إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة"

بعد طلب GADMediationRewardedLoadCompletionHandler باستخدام إعلان تم تحميله، يمكن للمحوّل استخدام عنصر التفويض GADMediationRewardedAdEventDelegate الذي تم عرضه لإعادة توجيه أحداث العرض من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة". تنفّذ الفئة SampleCustomEventRewarded البروتوكول SampleRewardedAdDelegate لإعادة توجيه عمليات رد الاتصال من شبكة الإعلانات النموذجية إلى حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.

من المهم أن يعيد توجيه الحدث المخصّص أكبر عدد ممكن من عمليات معاودة الاتصال هذه، لكي يتلقّى تطبيقك الأحداث المكافئة من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة. في ما يلي مثال على استخدام عمليات معاودة الاتصال:

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. يمكنك استخدامها مع شبكة إعلانية متوافقة أو تعديلها لعرض إعلانات مقابل مكافآت مخصّصة.