Halaman ini diterjemahkan oleh Cloud Translation API.

Peristiwa kustom iklan native

Prasyarat

Meminta iklan native

Saat item baris peristiwa kustom dijangkau dalam rantai mediasi waterfall, metode loadNativeAd:adConfiguration:completionHandler: dipanggil di nama kelas yang Anda berikan saat membuat peristiwa. Dalam kasus ini, metode tersebut berada di SampleCustomEvent, yang kemudian memanggil metode loadNativeAd:adConfiguration:completionHandler: di SampleCustomEventNative.

Untuk meminta iklan native, buat atau ubah kelas yang menerapkan GADMediationAdapter dan loadNativeAd:adConfiguration:completionHandler:. Jika class yang memperluas GADMediationAdapter sudah ada, implementasikan loadNativeAd:adConfiguration:completionHandler: di sana. Selain itu, buat class baru untuk mengimplementasikan GADMediationNativeAd.

Dalam contoh peristiwa kustom, SampleCustomEvent menerapkan antarmuka GADMediationAdapter, lalu didelegasikan ke SampleCustomEventNative.

Swift

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)
  }
}

Objective-C

#import "SampleCustomEvent.h"

@implementation SampleCustomEvent

SampleCustomEventNativeAd *sampleNativeAd;

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

SampleCustomEventNative` bertanggung jawab atas tugas berikut:

Memuat iklan native
Mengimplementasikan protokol GADMediationNativeAd.
Menerima dan melaporkan callback peristiwa iklan ke Google Mobile Ads SDK

Parameter opsional yang ditetapkan di UI AdMob adalah disertakan dalam konfigurasi iklan. Parameter ini dapat diakses melalui adConfiguration.credentials.settings[@"parameter"]. Parameter ini biasanya ID unit iklan yang diperlukan SDK jaringan iklan saat membuat instance objek iklan.

Swift

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)
  }
}

Objective-C

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

Apakah iklan berhasil diambil atau mengalami error, Anda akan memanggil GADMediationNativeAdLoadCompletionHandler. Jika berhasil, teruskan class yang mengimplementasikan GADMediationNativeAd dengan nilai nil untuk parameter {i>error<i}; jika terjadi kegagalan, teruskan error yang temukan.

Biasanya, metode ini diimplementasikan dalam callback dari SDK pihak ketiga yang diterapkan adaptor Anda. Untuk contoh ini, SDK Sampel memiliki SampleNativeAdDelegate dengan callback yang relevan:

Swift

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)
  }
}

Objective-C

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

Memetakan iklan native

SDK yang berbeda memiliki format unik untuk iklan native. Satu mungkin kembali objek yang berisi "judul" Misalnya, sementara yang lain mungkin memiliki "judul". Selain itu, metode yang digunakan untuk melacak tayangan dan memproses klik dapat bervariasi dari satu SDK ke SDK lainnya.

Untuk mengatasi masalah ini, ketika peristiwa kustom menerima objek iklan native dari SDK yang dimediasi, SDK harus menggunakan class yang mengimplementasikan GADMediationNativeAd, seperti SampleCustomEventNativeAd, untuk "memetakan" objek iklan native SDK yang dimediasi agar sama dengan antarmuka yang diharapkan oleh Google Mobile Ads SDK.

Sekarang kita akan melihat lebih dekat detail implementasi untuk SampleCustomEventNativeAd.

Simpan pemetaan Anda

GADMediationNativeAd diharapkan untuk menerapkan properti tertentu yang dipetakan dari properti SDK lain:

Swift

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
}

Objective-C

/// 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;
}

Beberapa jaringan yang dimediasi dapat menyediakan aset tambahan di luar yang ditentukan oleh Google Mobile Ads SDK. Protokol GADMediationNativeAd menyertakan metode yang disebut extraAssets yang digunakan Google Mobile Ads SDK untuk mengambil "ekstra" ini aset dari pembuat peta.

Memetakan aset gambar

Memetakan aset gambar lebih rumit daripada memetakan data yang lebih sederhana seperti NSString atau double. Gambar mungkin didownload secara otomatis atau ditampilkan sebagai nilai URL. Kepadatan piksel layar juga dapat bervariasi.

Untuk membantu Anda mengelola detail ini, Google Mobile Ads SDK menyediakan Class GADNativeAdImage. Informasi aset gambar (apakah UIImage itu sebenarnya objek atau hanya nilai NSURL) harus ditampilkan ke Google Mobile Ads SDK menggunakan class ini.

Berikut adalah cara class mapper menangani pembuatan GADNativeAdImage untuk menyimpan gambar ikon:

Swift

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

Objective-C

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

Peristiwa tayangan dan klik

Google Mobile Ads SDK dan SDK yang dimediasi perlu mengetahui kapan tayangan iklan atau klik terjadi, tetapi hanya satu SDK yang perlu melacak peristiwa ini. Ada ada dua pendekatan berbeda yang dapat digunakan peristiwa kustom, bergantung pada apakah SDK yang dimediasi mendukung pelacakan tayangan dan klik secara mandiri.

Melacak klik dan tayangan dengan Google Mobile Ads SDK

Jika SDK yang dimediasi tidak melakukan pelacakan klik dan tayangannya sendiri, menyediakan metode untuk mencatat klik dan tayangan, Google Mobile Ads SDK dapat melacak kejadian ini dan memberi tahu adaptor. Protokol GADMediationNativeAd mencakup dua metode: didRecordImpression: dan didRecordClickOnAssetWithName:view:viewController: yang dapat dilakukan peristiwa kustom terapkan untuk memanggil metode terkait pada objek iklan bawaan yang dimediasi:

Swift

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

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

Objective-C

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

Karena class yang mengimplementasikan GADMediationNativeAd menyimpan referensi ke objek iklan bawaan SDK Sampel, ia dapat memanggil yang sesuai pada objek tersebut untuk melaporkan klik atau tayangan. Perhatikan bahwa Metode didRecordClickOnAssetWithName:view:viewController: memerlukan satu parameter: objek View yang sesuai dengan aset iklan native yang diterima ketika diklik.

Melacak klik dan tayangan dengan SDK yang dimediasi

Beberapa SDK yang dimediasi mungkin memilih untuk melacak klik dan tayangannya sendiri. Di beberapa dalam hal ini, Anda harus mengimplementasikan handlesUserClicks dan handlesUserImpressions seperti yang ditunjukkan dalam cuplikan di bawah. Dengan kembali YES, Anda menyatakan bahwa peristiwa kustom bertanggung jawab untuk melacak peristiwa ini dan memberi tahu Google Mobile Ads SDK saat peristiwa tersebut terjadi.

Peristiwa kustom yang mengganti pelacakan klik dan tayangan dapat menggunakan didRenderInView: untuk meneruskan tampilan iklan native ke SDK yang dimediasi iklan native untuk memungkinkan SDK yang dimediasi melakukan pelacakan sebenarnya. Contoh SDK dari project contoh peristiwa kustom kami (tempat cuplikan kode panduan ini digunakan diambil) tidak menggunakan pendekatan ini' Namun, jika terjadi, kode peristiwa kustom akan memanggil metode setNativeAdView:view: seperti yang ditampilkan dalam cuplikan di bawah:

Swift

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)
}

Objective-C

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

Meneruskan peristiwa mediasi ke Google Mobile Ads SDK

Setelah Anda memanggil GADMediationNativeLoadCompletionHandler dengan iklan yang dimuat, delegasi GADMediationNativeAdEventDelegate yang ditampilkan kemudian dapat digunakan oleh adaptor untuk meneruskan kejadian presentasi dari SDK pihak ketiga ke Google Mobile Ads SDK.

Peristiwa kustom harus meneruskan callback ini sebanyak mungkin memungkinkan, sehingga aplikasi Anda menerima peristiwa yang setara ini dari SDK Iklan Seluler. Berikut adalah contoh penggunaan callback:

Ini menyelesaikan penerapan peristiwa kustom untuk iklan native. Contoh lengkap tersedia di GitHub.