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

اختيار النظام الأساسي: Android (إصدار تجريبي) Android iOS

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

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

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

عند الوصول إلى عنصر العرض الخاص بالحدث المخصّص في سلسلة "توسّط العرض الإعلاني بدون انقطاع"، يتم استدعاء الطريقة 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

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

يتم تضمين المَعلمة الاختيارية المحدّدة في واجهة المستخدم في إعدادات الإعلان. يمكن الوصول إلى المَعلمة من خلال 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 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]
  }
}

إعادة توجيه أحداث التوسّط إلى Google Mobile Ads SDK

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

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

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