Pengembangan Adaptor Mediasi Jaringan Iklan

Catatan: Penggunaan Google Mobile Ads SDK sehubungan dengan Layanan Mediasi diatur oleh Persyaratan Layanan Mediasi.

Panduan ini ditujukan untuk jaringan iklan yang ingin membuat adaptor mediasi. Jika Anda adalah penayang, lihat petunjuk mediasi penayang.

Adaptor mediasi adalah lapisan komunikasi antara jaringan iklan Anda dan Mediasi Google Mobile Ads. Adaptor menayangkan iklan dari jaringan iklan Anda sekaligus meneruskan peristiwa iklan yang relevan ke AdMob. Adaptor bertanggung jawab untuk menerapkan protokol GADMAdNetworkAdapter guna memastikannya memberikan kemampuan yang diperlukan.

Prasyarat

• Xcode 15.3 atau yang lebih tinggi
• Target deployment 8.0 atau yang lebih tinggi
• Header tambahan dari folder Mediation Adapters pada download Google Mobile Ads iOS SDK

Jaringan iklan Anda harus memiliki hubungan yang berfungsi dengan Google untuk membuat adaptor mediasi.

Contoh Jaringan Iklan

Panduan ini menunjukkan cara membuat adaptor untuk Sample Ad Network. Sample Ad Network SDK berisi kelas yang mewakili kelas yang ditawarkan oleh sebagian besar jaringan iklan:

@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

Lihat penerapan SDK contoh lengkap untuk informasi lebih lanjut tentang class ini.

Konektor

Adaptor mediasi berinteraksi dengan Google Mobile Ads SDK menggunakan objek yang menerapkan protokol GADMAdNetworkConnector. Selanjutnya, kita akan menyebut objek ini sebagai konektor. Konektor mengekspos informasi yang diperlukan untuk permintaan iklan dan menyediakan cara untuk memanggil kembali mediasi untuk peristiwa iklan dan interaksi pengguna. Konektor diberikan ke adaptor mediasi pada saat inisialisasi. Siapkan adaptor Anda untuk menyimpan konektor dalam variabel instance:

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

Parameter server

Jaringan iklan Anda mungkin memerlukan ID untuk mengenali penayang. Sample Ad Network, misalnya, memerlukan unit iklan. Parameter server yang diperlukan ini disediakan ke adaptor melalui metode credentials, yang menampilkan NSDictionary ID dan nilai yang sesuai. Baris kode berikut mengambil parameter server yang bernama ad_unit untuk Sample Ad Network dari konektor:

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

Penyiapan jaringan mediasi

Jaringan iklan harus memberi tahu AdMob tentang parameter server yang diperlukan untuk jaringannya. Tindakan ini memungkinkan AdMob mengonfigurasi jaringan Anda di frontend.

Saat mengaktifkan jaringan untuk mediasi di frontend, AdMob mengharuskan Anda memasukkan nilai yang diperlukan untuk membuat instance adaptor. Screenshot di bawah menunjukkan bahwa Application Placement Identifier (APID) diperlukan untuk Millennial Media dan App ID diperlukan untuk InMobi.

Baca artikel ini untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi jaringan iklan mediasi.

Membuat permintaan iklan mediasi

Permintaan banner

Untuk permintaan banner mediasi, metode getBannerWithSize akan segera dipanggil setelah instance adaptor dibuat. Metode ini tidak menampilkan apa pun. Fungsi ini memberikan sinyal ke adaptor untuk memulai pengambilan iklan asinkron melalui jaringan. Adaptor Anda harus memproses callback untuk SDK Anda. Jika SDK Anda tidak mendukung ukuran iklan yang diberikan atau tidak mendukung iklan banner, panggil metode adapter:didFailAd: pada konektor.

Penerapan getBannerWithSize untuk Sample Ad Network akan terlihat seperti ini:

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

Parameter penargetan tambahan

Konektor berisi beberapa informasi penargetan umum yang dapat Anda referensikan untuk penargetan iklan:

• userKeywords
• testMode
• childDirectedTreatment

Tambahan mediasi

Tambahan mediasi memungkinkan jaringan iklan Anda mendukung parameter atau input penargetan tambahan yang tidak tercakup dalam parameter permintaan tambahan yang disediakan oleh konektor. Fungsi ini dapat disediakan melalui class yang menerapkan protokol GADAdNetworkExtras. Class SampleAdNetworkExtras ditampilkan di bawah ini sebagai contoh:

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

@end

Penayang harus meneruskan instance subclass GADAdNetworkExtras Anda saat membuat permintaan iklan. Instance subclass GADAdNetworkExtras ini dapat diakses melalui konektor. Berikut adalah cara menggunakan tambahan mediasi saat membuat permintaan iklan untuk jaringan Anda:

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

Untuk memastikan subclass GADAdNetworkExtras dapat diakses melalui konektor, terapkan networkExtrasClass dan tampilkan subclass GADAdNetworkExtras Anda:

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

Jika adaptor Anda tidak menggunakan tambahan mediasi, metode networkExtrasClass akan menampilkan Nil.

Memberi tahu mediasi

Adaptor Anda harus menerapkan pemroses iklan untuk jaringan Anda dan meneruskan callback peristiwa iklan yang relevan melalui konektor. Tabel di bawah menjelaskan kapan harus memanggil setiap metode delegasi:

Metode	Waktu menelepon
adapter:didReceiveAdView:	Permintaan banner berhasil.
adapter:didFailAd:	Permintaan banner gagal.
adapterDidGetAdClick:	Banner diklik.
adapterWillPresentFullScreenModal:	Banner akan menampilkan overlay dalam aplikasi.
adapterWillDismissFullScreenModal:	Overlay dalam aplikasi akan ditutup.
adapterDidDismissFullScreenModal:	Overlay dalam aplikasi telah ditutup.
adapterWillLeaveApplication:	Aplikasi akan ditempatkan di latar belakang atau dihentikan karena pengguna mengklik iklan yang akan meluncurkan aplikasi lain.

Contoh berikut menerapkan antarmuka SampleBannerAdDelegate dari Sample Ad Network untuk meneruskan pesan error dan status:

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

Meluncurkan overlay dalam aplikasi versus aplikasi eksternal

Ketika banner diklik, iklan dapat membuka overlay layar penuh atau aplikasi eksternal (seperti Safari atau app store). Callback konektor yang akan dipanggil dalam dua kasus ini berbeda.

Jika klik banner membuka overlay layar penuh, panggil adapterWillPresentFullScreenModal: saat menampilkan overlay. Saat overlay ditutup, panggil adapterWillDismissFullScreenModal: dan adapterDidDismissFullScreenModal:.

Jika klik banner (atau klik overlay layar penuh) menyebabkan pengguna keluar dari aplikasi, panggil callback adapterWillLeaveApplication:.

Anda sekarang memiliki adaptor mediasi yang berfungsi untuk banner. Untuk referensi, implementasi lengkap SampleAdapter dapat ditemukan di GitHub.

Menerapkan adaptor interstisial

Penerapan adaptor untuk iklan interstisial mirip dengan iklan banner. Metode getInterstitial dipanggil segera setelah adaptor dibuat instance-nya. Metode ini tidak menampilkan apa pun. Adaptor diharapkan akan memulai pengambilan iklan asinkron melalui jaringan. Buat adaptor Anda bertindak sebagai delegasi bagi SDK untuk memproses callback. Jika SDK Anda tidak mendukung iklan interstisial, panggil metode adapter:didFailAd: konektor sebagai berikut:

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

Sama seperti MediationBannerAdapter, Anda dapat menerima identifikasi penayang dan informasi penargetan iklan dari konektor.

Memberi tahu mediasi

Adaptor Anda harus menerapkan delegasi iklan untuk jaringan Anda dan meneruskan callback peristiwa iklan yang relevan melalui konektor. Tabel di bawah menjelaskan kapan harus memanggil setiap metode delegasi:

Metode	Waktu menelepon
adapterDidReceiveInterstitial:	Permintaan interstisial berhasil.
adapter:didFailInterstitial:	Permintaan interstisial gagal.
adapterDidGetAdClick:	Interstisial diklik.
adapterWillPresentInterstitial:	Interstisial akan ditampilkan.
adapterWillDismissInterstitial:	Interstisial akan ditutup.
adapterDidDismissInterstitial:	Interstisial telah ditutup.
adapterWillLeaveApplication:	Aplikasi akan ditempatkan di latar belakang atau dihentikan karena pengguna mengklik iklan yang akan meluncurkan aplikasi lain.

Contoh berikut menerapkan antarmuka SampleInterstitialAdDelegate Sample Ad Network untuk meneruskan pesan error dan status:

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

Menayangkan interstisial

Setelah adaptor memanggil adapterDidReceiveInterstitial, buat menunggu untuk menampilkan interstisial hingga presentInterstitialFromRootViewController dipanggil. Developer aplikasi memutuskan waktu untuk menampilkan interstisial, yang mungkin beberapa menit setelah diterima.

Berikut adalah penerapan presentInterstitialFromRootViewController: untuk Sample Ad Network:

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

Adaptor mediasi Anda siap menangani iklan interstisial. Untuk referensi, implementasi lengkap SampleAdapter dapat ditemukan di GitHub.

FAQ

Haruskah saya menyertakan adaptor sebagai bagian dari pustaka SDK atau sebagai pustaka terpisah?

Sebaiknya sertakan adaptor sebagai bagian dari library SDK Anda, sehingga developer hanya perlu mereferensikan satu library untuk memasukkan jaringan Anda.

Apa yang harus saya lakukan jika adaptor saya hanya mendukung iklan banner?

Jika adaptor Anda hanya mendukung banner, minta adaptor tersebut meneruskan peristiwa error ke mediasi untuk permintaan interstisial:

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

Apa yang harus saya lakukan jika adaptor saya hanya mendukung iklan interstisial?

Jika adaptor Anda hanya mendukung interstisial, adaptor harus meneruskan peristiwa error ke mediasi untuk permintaan banner:

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