Zdarzenia niestandardowe reklam natywnych

Wymagania wstępne

Dokończ konfigurowanie zdarzeń niestandardowych.

Wysyłanie żądania reklamy natywnej

Gdy element zamówienia zdarzenia niestandardowego zostanie osiągnięty w łańcuchu zapośredniczenia kaskadowego, metoda loadNativeAd:adConfiguration:completionHandler: jest wywoływana na nazwa klasy podana podczas tworzenia niestandardowej . W tym przypadku ta metoda jest w komórce SampleCustomEvent, która następnie wywołuje metody loadNativeAd:adConfiguration:completionHandler: w SampleCustomEventNative

Aby wysłać żądanie reklamy natywnej, utwórz lub zmodyfikuj klasę, która implementuje GADMediationAdapter i loadNativeAd:adConfiguration:completionHandler:. Jeśli klasa, która rozszerza zakres GADMediationAdapter, już istnieje, zaimplementuj loadNativeAd:adConfiguration:completionHandler:. Dodatkowo utwórz nowej klasy do zaimplementowania GADMediationNativeAd.

W naszym przykładzie zdarzenia niestandardowego SampleCustomEvent implementuje interfejsu GADMediationAdapter, a następnie przekazuje SampleCustomEventNative.

import GoogleMobileAds

class SampleCustomEvent: NSObject, GADMediationAdapter {

  fileprivate var nativeAd: SampleCustomEventNativeAd?

  func loadNativeAd(
    for adConfiguration: GADMediationNativeAdConfiguration,
    completionHandler: @escaping GADMediationNativeAdLoadCompletionHandler
  ) {
    self.nativeAd = SampleCustomEventNativeAd()
    self.nativeAd?.loadNativeAd(
      for: adConfiguration, completionHandler: completionHandler)
  }
}

#import "SampleCustomEvent.h"

@implementation SampleCustomEvent

SampleCustomEventNativeAd *sampleNativeAd;

- (void)loadNativeAdForAdConfiguration:
            (GADMediationNativeAdConfiguration *)adConfiguration
                     completionHandler:
                         (GADMediationNativeAdLoadCompletionHandler)
                             completionHandler {
  sampleNative = [[SampleCustomEventNativeAd alloc] init];
  [sampleNative loadNativeAdForAdConfiguration:adConfiguration
                             completionHandler:completionHandler];
}

SampleCustomEventNative` odpowiada za te zadania:

• Wczytuję reklamę natywną

• Wdrażanie protokołu GADMediationNativeAd.

• Odbieranie i raportowanie wywołań zwrotnych zdarzeń reklamowych do pakietu SDK do reklam mobilnych Google

Opcjonalny parametr zdefiniowany w interfejsie AdMob to uwzględnionych w konfiguracji reklam. Dostęp do parametru można uzyskać za pomocą: adConfiguration.credentials.settings[@"parameter"] Ten parametr ma wartość zwykle jest to identyfikator jednostki reklamowej wymagany przez pakiet SDK sieci reklamowej utworzenie instancji obiektu reklamy.

class SampleCustomEventNativeAd: NSObject, GADMediationNativeAd {
  /// The Sample Ad Network native ad.
  var nativeAd: SampleNativeAd?

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

  /// Completion handler called after ad load
  var completionHandler: GADMediationNativeLoadCompletionHandler?

  func loadNativeAd(
    for adConfiguration: GADMediationNativeAdConfiguration,
    completionHandler: @escaping GADMediationNativeLoadCompletionHandler
  ) {
    let adLoader = SampleNativeAdLoader()
    let sampleRequest = SampleNativeAdRequest()

    // The Google Mobile Ads SDK requires the image assets to be downloaded
    // automatically unless the publisher specifies otherwise by using the
    // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If
    // your network doesn't have an option like this and instead only ever
    // returns URLs for images (rather than the images themselves), your adapter
    // should download image assets on behalf of the publisher. This should be
    // done after receiving the native ad object from your network's SDK, and
    // before calling the connector's adapter:didReceiveMediatedNativeAd: method.
    sampleRequest.shouldDownloadImages = true
    sampleRequest.preferredImageOrientation = NativeAdImageOrientation.any
    sampleRequest.shouldRequestMultipleImages = false
    let options = adConfiguration.options
    for loaderOptions: GADAdLoaderOptions in options {
      if let imageOptions = loaderOptions as? GADNativeAdImageAdLoaderOptions {
        sampleRequest.shouldRequestMultipleImages =
          imageOptions.shouldRequestMultipleImages
        // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is
        // YES, the adapter should send just the URLs for the images.
        sampleRequest.shouldDownloadImages = !imageOptions.disableImageLoading
      } else if let mediaOptions = loaderOptions
        as? GADNativeAdMediaAdLoaderOptions
      {
        switch mediaOptions.mediaAspectRatio {
        case GADMediaAspectRatio.landscape:
          sampleRequest.preferredImageOrientation =
            NativeAdImageOrientation.landscape
        case GADMediaAspectRatio.portrait:
          sampleRequest.preferredImageOrientation =
            NativeAdImageOrientation.portrait
        default:
          sampleRequest.preferredImageOrientation = NativeAdImageOrientation.any
        }
      }
    }
    // This custom event uses the server parameter to carry an ad unit ID, which
    // is the most common use case.
    adLoader.delegate = self
    adLoader.adUnitID =
      adConfiguration.credentials.settings["parameter"] as? String
    self.completionHandler = completionHandler
    adLoader.fetchAd(sampleRequest)
  }
}

#import "SampleCustomEventNativeAd.h"

@interface SampleCustomEventNativeAd () <SampleNativeAdDelegate,
                                         GADMediationNativeAd> {
  /// The sample native ad.
  SampleNativeAd *_nativeAd;

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

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

- (void)loadNativeAdForAdConfiguration:
            (GADMediationNativeAdConfiguration *)adConfiguration
                     completionHandler:(GADMediationNativeLoadCompletionHandler)
                                           completionHandler {
  __block atomic_flag completionHandlerCalled = ATOMIC_FLAG_INIT;
  __block GADMediationNativeLoadCompletionHandler originalCompletionHandler =
      [completionHandler copy];

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

    id<GADMediationNativeAdEventDelegate> 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;
  };

  SampleNativeAdLoader *adLoader = [[SampleNativeAdLoader alloc] init];
  SampleNativeAdRequest *sampleRequest = [[SampleNativeAdRequest alloc] init];

  // The Google Mobile Ads SDK requires the image assets to be downloaded
  // automatically unless the publisher specifies otherwise by using the
  // GADNativeAdImageAdLoaderOptions object's disableImageLoading property. If
  // your network doesn't have an option like this and instead only ever returns
  // URLs for images (rather than the images themselves), your adapter should
  // download image assets on behalf of the publisher. This should be done after
  // receiving the native ad object from your network's SDK, and before calling
  // the connector's adapter:didReceiveMediatedNativeAd: method.
  sampleRequest.shouldDownloadImages = YES;

  sampleRequest.preferredImageOrientation = NativeAdImageOrientationAny;
  sampleRequest.shouldRequestMultipleImages = NO;
  sampleRequest.testMode = adConfiguration.isTestRequest;

  for (GADAdLoaderOptions *loaderOptions in adConfiguration.options) {
    if ([loaderOptions isKindOfClass:[GADNativeAdImageAdLoaderOptions class]]) {
      GADNativeAdImageAdLoaderOptions *imageOptions =
          (GADNativeAdImageAdLoaderOptions *)loaderOptions;
      sampleRequest.shouldRequestMultipleImages =
          imageOptions.shouldRequestMultipleImages;

      // If the GADNativeAdImageAdLoaderOptions' disableImageLoading property is
      // YES, the adapter should send just the URLs for the images.
      sampleRequest.shouldDownloadImages = !imageOptions.disableImageLoading;
    } else if ([loaderOptions
                   isKindOfClass:[GADNativeAdMediaAdLoaderOptions class]]) {
      GADNativeAdMediaAdLoaderOptions *mediaOptions =
          (GADNativeAdMediaAdLoaderOptions *)loaderOptions;
      switch (mediaOptions.mediaAspectRatio) {
        case GADMediaAspectRatioLandscape:
          sampleRequest.preferredImageOrientation =
              NativeAdImageOrientationLandscape;
          break;
        case GADMediaAspectRatioPortrait:
          sampleRequest.preferredImageOrientation =
              NativeAdImageOrientationPortrait;
          break;
        default:
          sampleRequest.preferredImageOrientation = NativeAdImageOrientationAny;
          break;
      }
    } else if ([loaderOptions isKindOfClass:[GADNativeAdViewAdOptions class]]) {
      _nativeAdViewAdOptions = (GADNativeAdViewAdOptions *)loaderOptions;
    }
  }

  // This custom event uses the server parameter to carry an ad unit ID, which
  // is the most common use case.
  NSString *adUnit = adConfiguration.credentials.settings[@"parameter"];
  adLoader.adUnitID = adUnit;
  adLoader.delegate = self;

  [adLoader fetchAd:sampleRequest];
}

Jeśli reklama została pobrana lub napotka błąd, wywołałby GADMediationNativeAdLoadCompletionHandler. Jeśli się uda, przekaż klasę, która implementuje funkcję GADMediationNativeAd z wartością nil dla parametru błędu; w przypadku niepowodzenia przekaż komunikat o błędzie napotkano problem.

Te metody są zwykle implementowane wewnątrz wywołań zwrotnych z funkcji pakietu SDK innej firmy wdrożonego przez adapter. W tym przykładzie Przykładowy pakiet SDK zawiera SampleNativeAdDelegate z odpowiednimi wywołaniami zwrotnymi:

func adLoader(
  _ adLoader: SampleNativeAdLoader, didReceive nativeAd: SampleNativeAd
) {
  extraAssets = [
    SampleCustomEventConstantsSwift.awesomenessKey: nativeAd.degreeOfAwesomeness
      ?? ""
  ]

  if let image = nativeAd.image {
    images = [GADNativeAdImage(image: image)]
  } else {
    let imageUrl = URL(fileURLWithPath: nativeAd.imageURL)
    images = [GADNativeAdImage(url: imageUrl, scale: nativeAd.imageScale)]
  }
  if let mappedIcon = nativeAd.icon {
    icon = GADNativeAdImage(image: mappedIcon)
  } else {
    let iconURL = URL(fileURLWithPath: nativeAd.iconURL)
    icon = GADNativeAdImage(url: iconURL, scale: nativeAd.iconScale)
  }

  adChoicesView = SampleAdInfoView()
  self.nativeAd = nativeAd
  if let handler = completionHandler {
    delegate = handler(self, nil)
  }
}

func adLoader(
  _ adLoader: SampleNativeAdLoader,
  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)
  }
}

- (void)adLoader:(SampleNativeAdLoader *)adLoader
    didReceiveNativeAd:(SampleNativeAd *)nativeAd {
  if (nativeAd.image) {
    _images = @[ [[GADNativeAdImage alloc] initWithImage:nativeAd.image] ];
  } else {
    NSURL *imageURL = [[NSURL alloc] initFileURLWithPath:nativeAd.imageURL];
    _images = @[ [[GADNativeAdImage alloc] initWithURL:imageURL
                                                 scale:nativeAd.imageScale] ];
  }

  if (nativeAd.icon) {
    _icon = [[GADNativeAdImage alloc] initWithImage:nativeAd.icon];
  } else {
    NSURL *iconURL = [[NSURL alloc] initFileURLWithPath:nativeAd.iconURL];
    _icon = [[GADNativeAdImage alloc] initWithURL:iconURL
                                            scale:nativeAd.iconScale];
  }

  // The sample SDK provides an AdChoices view (SampleAdInfoView). If your SDK
  // provides image and click through URLs for its AdChoices icon instead of an
  // actual UIView, the adapter is responsible for downloading the icon image
  // and creating the AdChoices icon view.
  _adChoicesView = [[SampleAdInfoView alloc] init];
  _nativeAd = nativeAd;

  _adEventDelegate = _loadCompletionHandler(self, nil);
}

- (void)adLoader:(SampleNativeAdLoader *)adLoader
    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);
}

Mapowanie reklam natywnych

Każdy pakiet SDK ma własne unikalne formaty reklam natywnych. Jedna może wrócić obiekty zawierające „tytuł” a inne pole może mieć „headline”. Dodatkowo metody śledzenia wyświetleń i przetwarzania liczba kliknięć może być różna w zależności od pakietu SDK.

Aby rozwiązać te problemy, gdy zdarzenie niestandardowe otrzymuje obiekt reklamy natywnej z swojego zapośredniczonego pakietu SDK, powinna używać klasy, która implementuje GADMediationNativeAd, np. SampleCustomEventNativeAd, do „mapuj” obiekt reklamy natywnej pakietu SDK w ramach zapośredniczenia aby interfejs był zgodny z interfejsem SDK do reklam mobilnych Google.

Teraz przyjrzymy się bliżej szczegółom implementacji SampleCustomEventNativeAd

Przechowuj mapowania

GADMediationNativeAd ma implementować określone właściwości, które są zmapowane z innych usług pakietu SDK:

var nativeAd: SampleNativeAd?

var headline: String? {
  return nativeAd?.headline
}

var images: [GADNativeAdImage]?

var body: String? {
  return nativeAd?.body
}

var icon: GADNativeAdImage?

var callToAction: String? {
  return nativeAd?.callToAction
}

var starRating: NSDecimalNumber? {
  return nativeAd?.starRating
}

var store: String? {
  return nativeAd?.store
}

var price: String? {
  return nativeAd?.price
}

var advertiser: String? {
  return nativeAd?.advertiser
}

var extraAssets: [String: Any]? {
  return [
    SampleCustomEventConstantsSwift.awesomenessKey:
      nativeAd?.degreeOfAwesomeness
      ?? ""
  ]
}

var adChoicesView: UIView?

var mediaView: UIView? {
  return nativeAd?.mediaView
}

/// Used to store the ad's images. In order to implement the
/// GADMediationNativeAd protocol, we use this class to return the images
/// property.
NSArray<GADNativeAdImage *> *_images;

/// Used to store the ad's icon. In order to implement the GADMediationNativeAd
/// protocol, we use this class to return the icon property.
GADNativeAdImage *_icon;

/// Used to store the ad's ad choices view. In order to implement the
/// GADMediationNativeAd protocol, we use this class to return the adChoicesView
/// property.
UIView *_adChoicesView;

- (nullable NSString *)headline {
  return _nativeAd.headline;
}

- (nullable NSArray<GADNativeAdImage *> *)images {
  return _images;
}

- (nullable NSString *)body {
  return _nativeAd.body;
}

- (nullable GADNativeAdImage *)icon {
  return _icon;
}

- (nullable NSString *)callToAction {
  return _nativeAd.callToAction;
}

- (nullable NSDecimalNumber *)starRating {
  return _nativeAd.starRating;
}

- (nullable NSString *)store {
  return _nativeAd.store;
}

- (nullable NSString *)price {
  return _nativeAd.price;
}

- (nullable NSString *)advertiser {
  return _nativeAd.advertiser;
}

- (nullable NSDictionary<NSString *, id> *)extraAssets {
  return
      @{SampleCustomEventExtraKeyAwesomeness : _nativeAd.degreeOfAwesomeness};
}

- (nullable UIView *)adChoicesView {
  return _adChoicesView;
}

- (nullable UIView *)mediaView {
  return _nativeAd.mediaView;
}

- (BOOL)hasVideoContent {
  return self.mediaView != nil;
}

Niektóre sieci zapośredniczone mogą dostarczać dodatkowe zasoby poza tymi określonymi pakietu SDK do reklam mobilnych Google. Protokół GADMediationNativeAd zawiera metodę extraAssets, którego pakiet SDK do reklam mobilnych Google używa do pobierania te „ekstra” od twórcy map.

Komponenty z obrazem map

Mapowanie komponentów z obrazem jest bardziej skomplikowane niż mapowanie prostszych danych takie jak NSString lub double. Obrazy mogą być pobierane automatycznie lub zwracanych jako wartości adresów URL. Może też zmieniać się gęstość pikseli.

Aby pomóc Ci w zarządzaniu tymi informacjami, pakiet SDK do reklam mobilnych Google udostępnia GADNativeAdImage zajęcia. Informacje o komponencie z obrazem (rzeczywiste UIImage) lub tylko wartości NSURL) powinny być zwracane do pakietu SDK do reklam mobilnych Google. za pomocą tych zajęć.

Oto jak klasa mapper obsługuje tworzenie obiektu GADNativeAdImage do przechowywania obraz ikony:

if let image = nativeAd.image {
  images = [GADNativeAdImage(image: image)]
} else {
  let imageUrl = URL(fileURLWithPath: nativeAd.imageURL)
  images = [GADNativeAdImage(url: imageUrl, scale: nativeAd.imageScale)]
}

if (nativeAd.image) {
  _images = @[ [[GADNativeAdImage alloc] initWithImage:nativeAd.image] ];
} else {
  NSURL *imageURL = [[NSURL alloc] initFileURLWithPath:nativeAd.imageURL];
  _images = @[ [[GADNativeAdImage alloc] initWithURL:imageURL
                                               scale:nativeAd.imageScale] ];
}

Zdarzenia dotyczące wyświetleń i kliknięć

Zarówno pakiet SDK do reklam mobilnych Google, jak i pakiet zapośredniczony SDK muszą wiedzieć, kiedy wyświetlenie lub kliknięcie, ale tylko jeden pakiet SDK potrzebuje do ich śledzenia. OK to 2 różne metody stosowane przez zdarzenia niestandardowe w zależności od tego, zapośredniczony pakiet SDK samodzielnie obsługuje śledzenie wyświetleń i kliknięć.

Śledzenie kliknięć i wyświetleń za pomocą pakietu SDK do reklam mobilnych Google

Jeśli zapośredniczony pakiet SDK nie prowadzi własnego śledzenia wyświetleń i kliknięć, udostępnia metody rejestrowania kliknięć i wyświetleń, pakiet SDK do reklam mobilnych Google śledzić te zdarzenia i powiadomić adapter. Protokół GADMediationNativeAd obejmuje 2 metody: didRecordImpression: oraz didRecordClickOnAssetWithName:view:viewController:, jakie zdarzenia niestandardowe mogą zaimplementuj odpowiednią metodę w obiekcie zapośredniczonej reklamy natywnej:

func didRecordImpression() {
  nativeAd?.recordImpression()
}

func didRecordClickOnAsset(
  withName assetName: GADUnifiedNativeAssetIdentifier,
  view: UIView,
  wController: UIViewController
) {
  nativeAd?.handleClick(on: view)
}

- (void)didRecordImpression {
  if (self.nativeAd) {
    [self.nativeAd recordImpression];
  }
}

- (void)didRecordClickOnAssetWithName:(GADUnifiedNativeAssetIdentifier)assetName
                                 view:(UIView *)view
                       viewController:(UIViewController *)viewController {
  if (self.nativeAd) {
    [self.nativeAd handleClickOnView:view];
  }
}

Ponieważ klasa, która implementuje interfejs GADMediationNativeAd, zawiera odniesienie do obiektu reklamy natywnej przykładowego pakietu SDK, może wywoływać metodę odpowiednią metodę do zgłoszenia kliknięcia lub wyświetlenia. Pamiętaj, że parametr Metoda didRecordClickOnAssetWithName:view:viewController: wymaga pojedynczej parametr: obiekt View odpowiadający otrzymanemu zasobowi reklamy natywnej kliknięcie.

Śledzenie kliknięć i wyświetleń za pomocą zapośredniczonego pakietu SDK

Niektóre zapośredniczone pakiety SDK mogą preferować samodzielne śledzenie kliknięć i wyświetleń. W w takim przypadku zastosuj handlesUserClicks i handlesUserImpressions zgodnie z poniższym fragmentem kodu. Po powrocie YES, wskazujesz, że zdarzenie niestandardowe jest odpowiedzialne za śledzenie o tych zdarzeniach i powiadomi o nich pakiet SDK do reklam mobilnych Google.

Zdarzenia niestandardowe, które zastępują śledzenie kliknięć i wyświetleń, mogą używać parametru didRenderInView: wiadomość, która ma przekazać widok reklamy natywnej do pakietu SDK obsługującego zapośredniczenie obiektu reklamy natywnej, by umożliwić zapośredniczonemu pakietowi SDK rzeczywiste śledzenie. Przykład SDK z naszego przykładowego projektu dotyczącego zdarzeń niestandardowych (z którego w tym przewodniku znajdują się fragmenty kodu które zostały zajęte) nie stosuje tej metody”. ale jeśli tak, kod zdarzenia niestandardowego wywoła metodę setNativeAdView:view: zgodnie z poniższym fragmentem kodu:

func handlesUserClicks() -> Bool {
  return true
}
func handlesUserImpressions() -> Bool {
  return true
}

func didRender(
  in view: UIView, clickableAssetViews: [GADNativeAssetIdentifier: UIView],
  nonclickableAssetViews: [GADNativeAssetIdentifier: UIView],
  viewController: UIViewController
) {
  // This method is called when the native ad view is rendered. Here you would pass the UIView
  // back to the mediated network's SDK.
  self.nativeAd?.setNativeAdView(view)
}

- (BOOL)handlesUserClicks {
  return YES;
}

- (BOOL)handlesUserImpressions {
  return YES;
}

- (void)didRenderInView:(UIView *)view
       clickableAssetViews:(NSDictionary<GADNativeAssetIdentifier, UIView *> *)
                               clickableAssetViews
    nonclickableAssetViews:(NSDictionary<GADNativeAssetIdentifier, UIView *> *)
                               nonclickableAssetViews
            viewController:(UIViewController *)viewController {
  // This method is called when the native ad view is rendered. Here you would
  // pass the UIView back to the mediated network's SDK. Playing video using
  // SampleNativeAd's playVideo method
  [_nativeAd setNativeAdView:view];
}

Przekierowywanie zdarzeń zapośredniczenia do pakietu SDK do reklam mobilnych Google

Po połączeniu telefonu GADMediationNativeLoadCompletionHandler z wczytaną reklamą, zwrócony delegat GADMediationNativeAdEventDelegate może być następnie używany przez adapter do przekazywania zdarzeń prezentacji z zewnętrznego pakietu SDK do pakietu SDK do reklam mobilnych Google.

Ważne jest, aby zdarzenie niestandardowe przekazuje jak najwięcej z tych wywołań zwrotnych by aplikacja otrzymywała te same zdarzenia z Google Pakiet SDK do reklam mobilnych. Oto przykład użycia wywołań zwrotnych:

Spowoduje to zakończenie implementacji zdarzeń niestandardowych w przypadku reklam natywnych. Pełny przykład jest dostępny na GitHub