تنفيذ محوِّل إعلان يضم مكافأة

ملاحظة مهمة: استخدامك لحزمة SDK لإعلانات Google على الأجهزة الجوّالة في ما يتعلق بخدمات التوسّط يخضع لبنود خدمة التوسّط.

ويتلقى محوِّل التوسّط الرسائل والطلبات من حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة، كما يتواصل مع حزمة تطوير البرامج (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 من طريقة 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

الإبلاغ عن أرقام الإصدارات

يجب أن يقدّم المحوِّل تقريرًا إلى "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" عن إصدار المعدِّل نفسه وإصدار حزمة تطوير البرامج (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

تهيئة المحوّل

عند إعداد أحد التطبيقات لحزمة تطوير البرامج "SDK لإعلانات Google على الأجهزة الجوّالة"، يتم استدعاء setUpWithConfiguration:completionHandler: في جميع المحوِّلات التي تم ضبطها للتطبيق ضمن واجهة مستخدم AdMob.

توفر الوسيطة GADMediationServerConfiguration معلومات حول جميع مواضع الإعلانات التي تم ضبطها للتطبيق ضمن واجهة مستخدم AdMob. استخدِم هذه المعلومات لإعداد حزمة تطوير البرامج (SDK) لشبكة الإعلانات. بعد إعداد حزمة تطوير البرامج (SDK) لشبكة الإعلانات، يمكنك استدعاء الوسيطة GADMediationAdapterSetUpCompletionBlock. يتيح لك هذا الحظر الإبلاغ عن عملية إعداد ناجحة أو تعذّر إتمامها إلى "SDK لإعلانات Google على الأجهزة الجوّالة" من خلال استدعاء معالج الإكمال باستخدام كائن 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

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

عندما يُحمِّل تطبيق إعلانًا يضم مكافأة باستخدام "SDK لإعلانات Google على الأجهزة الجوّالة"، يتم استدعاء loadRewardedAdForAdConfiguration:completionHandler: في المحوِّل في حال الوصول إلى شبكة المواقع الإعلانية في تدفق التوسّط.

تتيح لك السمة GADRewardedLoadCompletionHandler الإبلاغ عن تحميل إعلان ناجح إلى "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" من خلال تقديم مرجع إلى عنصر يتوافق مع بروتوكول GADMediationRewardedAd، أو من خلال توفير مرجع nil وعنصر NSError. يؤدي استدعاء معالِج اكتمال التحميل إلى عرض GADMediationRewardedAdEventDelegate التي يجب أن يحتفظ بها المحوِّل حتى دورة حياة الإعلان لإبلاغ حزمة تطوير البرامج لإعلانات Google على الأجهزة الجوّالة بأي حدث لاحق.

#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) التابعة لجهة خارجية وتعيينها لمعاودة الاتصال المناسبة لحزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة.

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

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

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

عرض الإعلان

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

- (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];
}

إعداد تقارير عن أحداث الإعلانات في "حزمة تطوير البرامج (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];
}

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

حدث الإعلان	الوصف
willPresentFullScreenView	تُعلِم "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بأنّه سيتم عرض الإعلان.
didStartVideo	تُعلِم "حزمة تطوير البرامج لإعلانات Google على الأجهزة الجوّالة" ببدء عرض الإعلان الذي يضم مكافأة.
reportImpression	وتُعلِم حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بحدوث مرة ظهور للإعلان.
didEndVideo	تُعلِم "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بانتهاء عرض الإعلان الذي يضم مكافأة.
didRewardUserWithReward	يتم إرسال إشعار إلى حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" تفيد بأنّ المستخدم قد حصل على مكافأة.
reportClick	تُعلِم حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة بأنّه تم النقر على الإعلان.
willDismissFullScreenView	تُعلِم "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بأنّه سيتم إغلاق الإعلان.
didDismissFullScreenView	تُعلِم "حزمة تطوير البرامج (SDK) لإعلانات Google على الأجهزة الجوّالة" بأنّه قد تم إغلاق الإعلان.