Разработка адаптера медиации рекламной сети

Это руководство предназначено для рекламных сетей, желающих создать адаптер медиации. Если вы издатель, ознакомьтесь с инструкциями по посредничеству издателей .

Адаптер медиации – это уровень связи между вашей рекламной сетью и Google Mobile Ads Mediation. Адаптеры показывают объявления из вашей рекламной сети и пересылают соответствующие рекламные события в AdMob. Адаптер отвечает за реализацию протокола GADMAdNetworkAdapter чтобы гарантировать, что он предоставляет необходимые возможности.

Предварительные условия

  • Xcode 15.3 или выше
  • Цель развертывания 8.0 или выше
  • Дополнительные заголовки из папки «Адаптеры агрегатора» загрузки Google Mobile Ads iOS SDK.

Чтобы создать адаптер медиации, ваша рекламная сеть должна иметь налаженные рабочие отношения с 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 .

Разъем

Адаптеры медиации взаимодействуют с Google Mobile Ads SDK с помощью объекта, реализующего протокол 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 требует от вас ввода значений, необходимых для создания экземпляра вашего адаптера. На снимке экрана ниже показано, что для Millennial Media требуется идентификатор размещения приложения (APID), а для 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;
}