تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تطوير مهايئ وساطة شبكة الإعلانات

هذا الدليل مخصّص لشبكات المواقع الإعلانية التي تتطلّع إلى إنشاء محوّل توسّط. إذا كنت ناشرًا، راجِع تعليمات توسّط الناشرِين.

محوّل التوسط هو طبقة الاتصال بين شبكة الإعلانات وتوسّط إعلانات Google على الأجهزة الجوّالة. تعرض المحوّلات الإعلانات من شبكة المواقع الإعلانية مع إعادة توجيه أحداث الإعلانات ذات الصلة إلى AdMob. ويكون المحوِّل مسؤولًا عن تنفيذ بروتوكول GADMAdNetworkAdapter لضمان توفيره للإمكانات المطلوبة.

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

Xcode 15.3 أو إصدار أحدث
الإصدار 8.0 أو الإصدارات الأحدث للنشر المستهدَف
رؤوس إضافية من مجلد "محوّلات التوسّط" في عملية تنزيل حزمة "SDK لإعلانات Google على الأجهزة الجوّالة" لنظام التشغيل iOS

يجب أن تتمتع شبكة الإعلانات بعلاقة عمل متينة مع Google حتى تتمكن من إنشاء محوّل توسط.

نموذج شبكة إعلانات

يعرض هذا الدليل كيفية إنشاء محوّل لنماذج شبكة الإعلانات. يحتوي نموذج حزمة تطوير البرامج (SDK) لشبكة الإعلانات على فئات تمثّل الفئات التي تقدّمها معظم شبكات الإعلانات:

@interface SampleBanner : UILabel

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleBannerAdDelegate> delegate;
- (void)fetchAd:(SampleAdRequest *)request;

@end

typedef NS_ENUM(NSInteger, SampleErrorCode) {
  SampleErrorCodeBadRequest = 0,
  SampleErrorCodeUnknown = 1,
  SampleErrorCodeNetworkError = 2,
  SampleErrorCodeNoInventory = 3,
};

@interface SampleAdRequest : NSObject

@property(nonatomic, assign) BOOL testMode;
@property(nonatomic, copy) NSArray *keywords;

@end

@interface SampleInterstitial : NSObject

@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleInterstitialAdDelegate> delegate;
@property(nonatomic, assign, getter=isInterstitialLoaded) BOOL interstitialLoaded;
- (void)fetchAd:(SampleAdRequest *)request;
- (void)show;

@end

@protocol SampleBannerAdDelegate
- (void)bannerDidLoad:(SampleBanner *)banner;
- (void)banner:(SampleBanner *)banner didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)bannerWillLeaveApplication:(SampleBanner *)banner;

@end

@protocol SampleInterstitialAdDelegate<NSObject>
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial;
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial;

@end

يمكنك الاطّلاع على نموذج كامل لتنفيذ حزمة تطوير البرامج (SDK)للحصول على مزيد من المعلومات حول هذه الفئات.

الموصِّل

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

- (id)initWithGADMAdNetworkConnector:(id<GADMAdNetworkConnector>)c {
  if ((self = [super init])) {
    _connector = c;
  }
  return self;
}

مَعلمات الخادم

من المحتمل أن تحتاج شبكة الإعلانات التي تستخدمها إلى معرّفات لتحديد هوية الناشر. على سبيل المثال، يتطلب نموذج شبكة الإعلانات وحدة إعلانية يتم تقديم معلَمات الخادم المطلوبة هذه إلى المحوّل من خلال طريقة credentials التي تعرض NSDictionary من المعرّفات والقيم المقابلة. يسترد سطر الرمز التالي معلمة الخادم المسماة ad_unit لنموذج شبكة الإعلانات من الموصل:

self.interstitialAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

إعداد شبكة التوسّط

يجب على شبكات الإعلانات إبلاغ AdMob بمعلمات الخادم المطلوبة لشبكتها. يمكّن هذا AdMob من تهيئة شبكتك في الواجهة الأمامية.

عند تفعيل شبكتك للتوسّط في الواجهة الأمامية، تطلب منك AdMob إدخال القيم اللازمة لإنشاء مثيل للمحوّل. توضّح لقطة الشاشة أدناه أنّ معرّف موضع التطبيق (APID) مطلوب لـ Millennial Media ورقم تعريف التطبيق مطلوب لـ InMobi.

اطّلع على هذه المقالة للحصول على مزيد من المعلومات حول تهيئة شبكات إعلانات التوسط.

تقديم طلب إعلان توسط

طلب بانر

بالنسبة إلى طلبات بانر التوسّط، يتم استدعاء طريقة getBannerWithSize مباشرةً بعد إنشاء مثيل للمحوِّل. لا ترجع هذه الطريقة أي شيء. وتُرسل هذه الميزة إشارة إلى المحوّل لبدء عملية استرجاع الإعلانات غير المتزامنة عبر الشبكة. اطلب من المحوّل الاستماع إلى معاودة الاتصال الخاصة بحزمة تطوير البرامج (SDK). إذا كانت حزمة تطوير البرامج (SDK) لا تتوافق مع حجم الإعلان المحدّد أو لا توفّر إعلانات البانر، عليك استدعاء طريقة adapter:didFailAd: على الموصِّل.

يبدو تنفيذ getBannerWithSize لنموذج شبكة إعلانات على النحو التالي:

- (void)getBannerWithSize:(GADAdSize)adSize {
  //The adapter should fail immediately if the adSize is not supported
  if (!GADAdSizeEqualToSize(adSize, GADAdSizeBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeMediumRectangle) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeFullBanner) &&
      !GADAdSizeEqualToSize(adSize, GADAdSizeLeaderboard)) {
    NSString *errorDesc =
        [NSString stringWithFormat:@"Invalid ad type %@, not going to get ad.",
                                   NSStringFromGADAdSize(adSize)];
    NSDictionary *errorInfo = [NSDictionary
        dictionaryWithObjectsAndKeys:errorDesc, NSLocalizedDescriptionKey, nil];
    NSError *error = [NSError errorWithDomain:GADErrorDomain
                                         code:GADErrorMediationInvalidAdSize
                                     userInfo:errorInfo];
    [self.connector adapter:self didFailAd:error];
    return;
  }
  self.bannerAd = [[SampleBanner alloc]
      initWithFrame:CGRectMake(0, 0, adSize.size.width, adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];

  // Setup request parameters.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;
  [self.bannerAd fetchAd:request];
  NSLog(@"Requesting banner from Sample Ad Network");
}

معلمات استهداف إضافية

يحتوي الموصِّل على بعض معلومات الاستهداف الشائعة التي يمكنك الرجوع إليها لاستهداف الإعلانات:

userKeywords
testMode
childDirectedTreatment

إضافات التوسّط

تسمح الإضافات الإضافية للتوسّط لشبكتك الإعلانية بدعم معلمات استهداف إضافية أو مدخلات إضافية لا تغطيها معلمات الطلب الإضافية التي يوفرها الموصل. ويمكن توفير هذه الوظيفة من خلال فئة تنفّذ بروتوكول GADAdNetworkExtras. نوضّح فئة SampleAdNetworkExtras في ما يلي كمثال:

@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// Should ad volume audio be muted.
@property(nonatomic, assign) BOOL muteAudio;

@end

على الناشرين اجتياز مثيل من الفئة الفرعية GADAdNetworkExtras عند تقديم طلب إعلان. يمكن الوصول إلى هذا المثال من الفئة الفرعية GADAdNetworkExtras من خلال الموصل. في ما يلي كيفية استخدام إضافات التوسط عند إنشاء طلب إعلان لشبكتك:

SampleAdRequest *request = [[SampleAdRequest alloc] init];
SampleAdNetworkExtras *myAdNetworkExtras = [self.connector networkExtras];
request.muteAudio = myAdNetworkExtras.muteAudio;
[self.bannerAd fetchAd:request];

لضمان إمكانية الوصول إلى الفئة الفرعية GADAdNetworkExtras من خلال الموصل، نفِّذ سياسة networkExtrasClass وأرجع الفئة الفرعية GADAdNetworkExtras:

+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleAdNetworkExtras class];
}

إذا كان المحوّل لا يستخدم إضافات توسّط، تعرض طريقة networkExtrasClass Nil.

إشعار الوساطة

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

الطريقة	وقت الاتصال
`adapter:didReceiveAdView:`	نجح طلب البانر.
`adapter:didFailAd:`	تعذّر طلب البانر.
`adapterDidGetAdClick:`	تم النقر على البانر.
`adapterWillPresentFullScreenModal:`	سيعرِض البانر إعلانًا مركّبًا داخل التطبيق.
`adapterWillDismissFullScreenModal:`	سيتم إغلاق التراكب داخل التطبيق.
`adapterDidDismissFullScreenModal:`	تم إغلاق الإعلان المركّب على سطح التطبيق داخل التطبيق.
`adapterWillLeaveApplication:`	سيتم وضع التطبيق في الخلفية أو إنهاؤه لأنّ المستخدم نقر على إعلان سيؤدي إلى تشغيل تطبيق آخر.

ينفّذ المثال التالي واجهة SampleBannerAdDelegate من "نموذج شبكة إعلانات" لإعادة توجيه رسائل الخطأ والحالة:

- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.connector adapter:self didReceiveAdView:banner];
}

- (void)banner:(SampleBanner *)banner didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
                didFailAd:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.connector adapterDidGetAdClick:self];
  [self.connector adapterWillLeaveApplication:self];
}

تشغيل إعلان يظهر على سطح الفيديو داخل التطبيق مقارنةً بتطبيق خارجي

عند النقر على إعلان بانر، قد يفتح الإعلان إعلانًا بملء الشاشة أو تطبيقًا خارجيًا (مثل متصفّح Safari أو متجر التطبيقات). تختلف استدعاءات الموصل المراد استدعاءها في هاتين الحالتين.

إذا أدّت النقر على البانر إلى فتح إعلان بملء الشاشة، استدعِ adapterWillPresentFullScreenModal: عند عرض النص المركّب. عند إغلاق التراكب، استدعِ كلاً من adapterWillDismissFullScreenModal: و adapterDidDismissFullScreenModal:.

إذا تسبّبت نقرة على البانر (أو النقر على تراكب ملء الشاشة) في مغادرة المستخدِم للتطبيق، عليك استدعاء معاودة الاتصال adapterWillLeaveApplication:.

لديك الآن محوِّل توسّط قيد التشغيل لإعلانات البانر. كمرجع لك، يمكنك الاطّلاع على عملية تنفيذ كاملة لـ SampleAdapter على GitHub.

تنفيذ محوّل بيني

يتشابه تنفيذ المحوّل للإعلانات البينية مع إعلانات البانر. ويتم استدعاء طريقة getInterstitial فور إجراء عملية التحقق من المحوّل. ولا تؤدي هذه الطريقة إلى عرض أي بيانات. من المتوقّع أن يبدأ المحوّل عملية استرجاع الإعلانات غير المتزامنة عبر الشبكة اجعل المحول يعمل كمفوض لحزمة SDK للاستماع إلى عمليات معاودة الاتصال. إذا كانت حزمة تطوير البرامج (SDK) لا تتوافق مع الإعلانات البينية، يمكنك استدعاء طريقة adapter:didFailAd: في الموصِّل على النحو التالي:

- (void)getInterstitial {
  self.interstitialAd = [[SampleInterstitial alloc] init];
  self.interstitialAd.delegate = self;
  self.interstitialAd.adUnit =
      [[self.connector credentials] objectForKey:@"ad_unit"];

  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  // Setup request parameters.
  request.testMode = self.connector.testMode;
  request.keywords = self.connector.userKeywords;

  [self.interstitialAd fetchAd:request];
  NSLog(@"Requesting interstitial from Sample Ad Network");
}

تمامًا كما هو الحال في MediationBannerAdapter، يمكنك الحصول على معلومات تعريف الناشر واستهداف الإعلانات من الموصِّل.

إشعار الوساطة

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

الطريقة	وقت الاتصال
`adapterDidReceiveInterstitial:`	تم إرسال الطلب البيني بنجاح.
`adapter:didFailInterstitial:`	تعذّر طلب الإعلان البيني.
`adapterDidGetAdClick:`	تم النقر على الإعلان البيني.
`adapterWillPresentInterstitial:`	سيتم عرض الإعلان البيني.
`adapterWillDismissInterstitial:`	سيتم إغلاق الإعلان البيني.
`adapterDidDismissInterstitial:`	تم إغلاق الإعلان البيني.
`adapterWillLeaveApplication:`	سيبدأ التطبيق في الخلفية أو سيتم إنهاؤه بسبب نقر المستخدم على إعلان سيؤدي إلى تشغيل تطبيق آخر.

ينفّذ المثال التالي واجهة SampleInterstitialAdDelegate لنموذج شبكة الإعلانات لإعادة توجيه رسائل الخطأ والحالة:

- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.connector adapterDidReceiveInterstitial:self];
}

- (void)interstitial:(SampleInterstitial *)interstitial
    didFailWithError:(SampleErrorCode)error {
  [self.connector adapter:self
      didFailInterstitial:[NSError errorWithDomain:@"Ad request failed"
                                              code:error
                                          userInfo:nil]];
}

- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillPresentInterstitial:self];
}

- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterWillDismissInterstitial:self];
}

- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.connector adapterDidDismissInterstitial:self];
}

عرض إعلان بيني

بعد استدعاء المحوِّل adapterDidReceiveInterstitial، انتظِر لعرض الإعلان البيني حتى يتم طلب presentInterstitialFromRootViewController. يقرر مطور التطبيق وقت عرض الإعلان البيني، والذي قد يكون عدة دقائق بعد استلامه.

في ما يلي تطبيق لعلامة presentInterstitialFromRootViewController: لنموذج شبكة الإعلانات:

- (void)presentInterstitialFromRootViewController:
    (UIViewController *)rootViewController {
  if ([self.interstitialAd isLoaded]) {
    [self.interstitialAd show];
  }
}

محوّل التوسط جاهز للتعامل مع الإعلانات البينية. كمرجع لك، يمكن العثور على عملية تنفيذ كاملة لـ SampleAdapter على GitHub.

الأسئلة الشائعة

هل يجب تضمين المحوّل كجزء من مكتبة حزمة تطوير البرامج (SDK) أم كمكتبة منفصلة؟

ننصحك بتضمين المحوِّل كجزء من مكتبة SDK لكي لا يضطر المطوّرون إلى الرجوع إلى سوى مكتبة واحدة لدمج شبكتك.

ماذا أفعل إذا كان المحوّل يتيح إعلانات البانر فقط؟

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

- (void)getInterstitial {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error = [NSError errorWithDomain:GADErrorDomain
                                       code:GADErrorInvalidRequest
                                   userInfo:errorInfo];
  [self.connector adapter:self didFailInterstitial:error];
  return;
}

ماذا أفعل إذا كان المحوّل يتيح عرض الإعلانات البينية فقط؟

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

- (void)getBannerWithSize:(GADAdSize)adSize {
  NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" };
  NSError *error =
      [NSError errorWithDomain:GADErrorDomain
                          code:GADErrorInvalidRequest
                      userInfo:errorInfo];
  [self.connector adapter:self didFailAd:error];
  return;
}