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

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

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

طلب إعلان بيني

عند الوصول إلى عنصر العرض الخاص بالحدث المخصّص في سلسلة "توسّط العرض الإعلاني بدون انقطاع"، يتم استدعاء الطريقة loadInterstitial:adConfiguration:completionHandler: في اسم الفئة الذي قدّمته عند إنشاء حدث مخصّص. في هذه الحالة، تكون الطريقة في SampleCustomEvent، والتي تستدعي بعد ذلك الطريقة loadInterstitial:adConfiguration:completionHandler: في SampleCustomEventInterstitial.

لطلب إعلان بيني، أنشئ أو عدِّل فئة تنفّذ GADMediationAdapter وloadInterstitial:adConfiguration:completionHandler:. إذا كان هناك صف يوسّع GADMediationAdapter، عليك تنفيذ loadInterstitial:adConfiguration:completionHandler: هناك. بالإضافة إلى ذلك، أنشئ فئة جديدة لتنفيذ GADMediationInterstitialAd.

في مثال الحدث المخصّص، تنفّذ SampleCustomEvent الواجهة GADMediationAdapter ثم تفوّض إلى SampleCustomEventInterstitial.

Swift

import GoogleMobileAds

class SampleCustomEvent: NSObject, MediationAdapter {

  fileprivate var interstitialAd: SampleCustomEventInterstitial?
  ...

  func loadInterstitial(
    for adConfiguration: MediationInterstitialAdConfiguration,
    completionHandler: @escaping GADMediationInterstitialLoadCompletionHandler
  ) {
    self.interstitialAd = SampleCustomEventInterstitial()
    self.interstitialAd?.loadInterstitial(
      for: adConfiguration, completionHandler: completionHandler)
  }
}

Objective-C

#import "SampleCustomEvent.h"

@implementation SampleCustomEvent

SampleCustomEventInterstitial *sampleInterstitial;

- (void)loadInterstitialForAdConfiguration:
            (GADMediationInterstitialAdConfiguration *)adConfiguration
                         completionHandler:
                             (GADMediationInterstitialLoadCompletionHandler)
                                 completionHandler {
  sampleInterstitial = [[SampleCustomEventInterstitial alloc] init];
  [sampleInterstitial loadInterstitialForAdConfiguration:adConfiguration
                                       completionHandler:completionHandler];
}

تتحمّل "SampleCustomEventInterstitial" مسؤولية المهام التالية:

• تحميل الإعلان البيني واستدعاء طريقة GADMediationInterstitialAdLoadCompletionHandler بعد اكتمال التحميل

• تنفيذ بروتوكول GADMediationInterstitialAd

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

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة المستخدم في إعدادات الإعلان. يمكن الوصول إلى المَعلمة من خلال adConfiguration.credentials.settings[@"parameter"]. عادةً ما تكون هذه المَعلمة معرّف وحدة إعلانية تتطلّبه حزمة SDK لشبكة إعلانية عند إنشاء مثيل لكائن إعلان.

Swift

import GoogleMobileAds

class SampleCustomEventInterstitial: NSObject, MediationInterstitialAd {
  /// The Sample Ad Network interstitial ad.
  var interstitial: SampleInterstitial?

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

  var completionHandler: GADMediationInterstitialLoadCompletionHandler?

  func loadInterstitial(
    for adConfiguration: MediationInterstitialAdConfiguration,
    completionHandler: @escaping GADMediationInterstitialLoadCompletionHandler
  ) {
    interstitial = SampleInterstitial.init(
      adUnitID: adConfiguration.credentials.settings["parameter"] as? String)
    interstitial?.delegate = self
    let adRequest = SampleAdRequest()
    adRequest.testMode = adConfiguration.isTestRequest
    self.completionHandler = completionHandler
    interstitial?.fetchAd(adRequest)
  }

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

Objective-C

#import "SampleCustomEventInterstitial.h"

@interface SampleCustomEventInterstitial () <SampleInterstitialAdDelegate,
                                             GADMediationInterstitialAd> {
  /// The sample interstitial ad.
  SampleInterstitial *_interstitialAd;

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

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

- (void)loadInterstitialForAdConfiguration:
            (GADMediationInterstitialAdConfiguration *)adConfiguration
                         completionHandler:
                             (GADMediationInterstitialLoadCompletionHandler)
                                 completionHandler {
  __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
  __block GADMediationInterstitialLoadCompletionHandler
      originalCompletionHandler = [completionHandler copy];

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

    id<GADMediationInterstitialAdEventDelegate> 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"];
  _interstitialAd = [[SampleInterstitial alloc] initWithAdUnitID:adUnit];
  _interstitialAd.delegate = self;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = adConfiguration.isTestRequest;
  [_interstitialAd fetchAd:adRequest];
}

سواء تم جلب الإعلان بنجاح أو حدث خطأ، عليك استدعاء GADMediationInterstitialLoadCompletionHandler. في حال النجاح، مرِّر الفئة التي تنفّذ GADMediationInterstitialAd مع قيمة nil لمَعلمة الخطأ. وفي حال حدوث خطأ، مرِّر الخطأ الذي واجهته.

عادةً، يتم تنفيذ هذه الطرق داخل عمليات ردّ الاتصال من حزمة تطوير البرامج (SDK) التابعة لجهة خارجية التي ينفّذها المحوّل. في هذا المثال، تحتوي حزمة تطوير البرامج (SDK) النموذجية على SampleInterstitialAdDelegate مع عمليات رد اتصال ذات صلة:

Swift

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

func interstitial(
  _ interstitial: SampleInterstitial,
  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)interstitialDidLoad:(SampleInterstitial *)interstitial {
  _adEventDelegate = _loadCompletionHandler(self, nil);
}

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

يتطلّب GADMediationInterstitialAd تنفيذ طريقة present لعرض الإعلان:

Swift

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

Objective-C

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

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

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

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

Swift

func interstitialWillPresentScreen(_ interstitial: SampleInterstitial) {
  delegate?.willPresentFullScreenView()
  delegate?.reportImpression()
}

func interstitialWillDismissScreen(_ interstitial: SampleInterstitial) {
  delegate?.willDismissFullScreenView()
}

func interstitialDidDismissScreen(_ interstitial: SampleInterstitial) {
  delegate?.didDismissFullScreenView()
}

func interstitialWillLeaveApplication(_ interstitial: SampleInterstitial) {
  delegate?.reportClick()
}

Objective-C

- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [_adEventDelegate willPresentFullScreenView];
  [_adEventDelegate reportImpression];
}

- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [_adEventDelegate willDismissFullScreenView];
}

- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [_adEventDelegate didDismissFullScreenView];
}

- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
  [_adEventDelegate reportClick];
}

بهذا يكتمل تنفيذ الأحداث المخصّصة للإعلانات البينية. يتوفّر المثال الكامل على GitHub. يمكنك استخدامها مع شبكة إعلانية متوافقة أو تعديلها لعرض إعلانات بينية للأحداث المخصّصة.