Opracowywanie adaptera zapośredniczenia sieci reklamowej

Uwaga: korzystanie z pakietu SDK do reklam mobilnych Google w połączeniu z usługami zapośredniczenia podlega Warunkom korzystania z zapośredniczenia.

Ten przewodnik jest przeznaczony dla sieci reklamowych, które chcą utworzyć adapter zapośredniczenia. Jeśli jesteś wydawcą, zapoznaj się z instrukcjami zapośredniczenia wydawcy.

Adapter zapośredniczenia to warstwa komunikacji między siecią reklamową a zapośredniczeniem reklam mobilnych Google. Adaptery wyświetlają reklamy z Twojej sieci reklamowej, a jednocześnie przekierowują odpowiednie zdarzenia reklamowe do AdMob. Adapter jest odpowiedzialny za wdrożenie protokołu GADMAdNetworkAdapter, aby zapewnić zgodność z wymaganymi funkcjami.

Wymagania wstępne

• Xcode 15.3 lub nowsza
• Cel wdrożenia 8.0 lub nowszy
• Dodatkowe nagłówki z folderu Mediation Adapters pakietu SDK do reklam mobilnych Google na iOS do pobrania

Aby utworzyć adapter zapośredniczenia, Twoja sieć reklamowa musi mieć umocnioną relację biznesową z Google.

Przykładowa sieć reklamowa

W tym przewodniku pokazujemy, jak utworzyć adapter na potrzeby przykładowej sieci reklamowej. Pakiet SDK przykładowej sieci reklamowej zawiera klasy reprezentatywne dla klas oferowanych przez większość sieci reklamowych:

@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

Więcej informacji o tych klasach znajdziesz w pełnej przykładowej implementacji pakietu SDK.

Oprogramowanie sprzęgające

Adaptery zapośredniczenia wchodzą w interakcję z pakietem SDK do reklam mobilnych Google za pomocą obiektu implementującego protokół GADMAdNetworkConnector. Teraz nazwiemy go „łącznikiem”. Oprogramowanie sprzęgające udostępnia informacje niezbędne do obsługi żądań reklamy oraz udostępnia sposób wywołania zwrotnego do zapośredniczenia w przypadku zdarzeń reklamowych i interakcji użytkowników. Oprogramowanie sprzęgające jest dostarczane do adapterów zapośredniczenia w momencie inicjowania. Skonfiguruj adapter tak, aby zapisywał oprogramowanie sprzęgające w zmiennej instancji:

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

Parametry serwera

Twoja sieć reklamowa prawdopodobnie potrzebuje identyfikatorów do identyfikacji wydawcy. Przykładowa sieć reklamowa wymaga na przykład jednostki reklamowej. Te wymagane parametry serwera są dostarczane do adaptera za pomocą metody credentials, która zwraca NSDictionary identyfikatorów i odpowiadających im wartości. Ten wiersz kodu pobiera z oprogramowania sprzęgające parametr serwera o nazwie ad_unit na potrzeby przykładowej sieci reklamowej:

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

Konfiguracja sieci zapośredniczeń

Sieci reklamowe muszą przekazywać do AdMob informacje o parametrach serwera wymaganych w ich sieci. Dzięki temu AdMob może konfigurować Twoją sieć w interfejsie.

Gdy włączysz zapośredniczenie w sieci w interfejsie, AdMob wymaga podania wartości niezbędnych do utworzenia instancji adaptera. Na poniższym zrzucie ekranu widać, że w przypadku Millennial Media wymagany jest identyfikator aplikacji (Application Placement Identifier, APID), a dla InMobi – identyfikator aplikacji.

Więcej informacji o konfigurowaniu sieci reklamowych z zapośredniczeniem znajdziesz w tym artykule.

Tworzenie żądania reklamy z zapośredniczeniem

Prośba o baner

W przypadku żądań banera zapośredniczenia metoda getBannerWithSize jest wywoływana bezpośrednio po utworzeniu instancji adaptera. Ta metoda niczego nie zwraca. Informuje ona adapter, że ma rozpocząć asynchroniczne pobieranie reklam przez sieć. Twój adapter powinien nasłuchiwać wywołań zwrotnych z pakietu SDK. Jeśli Twój pakiet SDK nie obsługuje podanego rozmiaru reklamy lub nie obsługuje banerów reklamowych, wywołaj w oprogramowaniu sprzęgającym metodę adapter:didFailAd:.

Implementacja usługi getBannerWithSize w przypadku przykładowej sieci reklamowej wygląda tak:

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

Dodatkowe parametry kierowania

Zawiera ono kilka wspólnych informacji o kierowaniu, które umożliwiają kierowanie reklam:

• userKeywords
• testMode
• childDirectedTreatment

Dodatki do zapośredniczenia

Dodatki do zapośredniczenia pozwalają sieci reklamowej na obsługę dodatkowych parametrów kierowania lub danych wejściowych, których nie obejmują dodatkowe parametry żądania dostarczane przez oprogramowanie sprzęgające. Tę funkcję można udostępniać za pomocą klasy implementującej protokół GADAdNetworkExtras. Klasa SampleAdNetworkExtras jest przedstawiona poniżej jako przykład:

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

@end

Podczas wysyłania żądania reklamy wydawcy muszą przekazać wystąpienie podklasy GADAdNetworkExtras. Dostęp do tej instancji podklasy GADAdNetworkExtras można uzyskać przez oprogramowanie sprzęgające. Oto jak możesz używać dodatkowych funkcji zapośredniczenia przy tworzeniu żądania reklamy dla swojej sieci:

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

Aby zapewnić dostęp do podklasy GADAdNetworkExtras za pomocą oprogramowania sprzęgającego, zaimplementuj networkExtrasClass i zwróć podklasę GADAdNetworkExtras:

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

Jeśli Twój adapter nie używa dodatków do zapośredniczenia, metoda networkExtrasClass zwraca wartość Nil.

Powiadom zapośredniczenie

Poproś adapter o zaimplementowanie odbiornika reklam w Twojej sieci i przekierowanie odpowiednich wywołań zwrotnych zdarzeń reklamowych przez oprogramowanie sprzęgające. W tabeli poniżej znajdziesz informacje o tym, kiedy wywoływać poszczególne metody przekazywania dostępu:

Metoda	Kiedy dzwonić
adapter:didReceiveAdView:	Żądanie banera zostało zrealizowane.
adapter:didFailAd:	Nie udało się zrealizować prośby o baner.
adapterDidGetAdClick:	Kliknięto baner.
adapterWillPresentFullScreenModal:	Na banerze pojawi się nakładka w aplikacji.
adapterWillDismissFullScreenModal:	Nakładka w aplikacji zostanie zamknięta.
adapterDidDismissFullScreenModal:	Nakładka w aplikacji została zamknięta.
adapterWillLeaveApplication:	Aplikacja zostanie umieszczona w tle lub zamknięta, ponieważ użytkownik kliknął reklamę, która spowoduje uruchomienie innej aplikacji.

W poniższym przykładzie zaimplementowano interfejs SampleBannerAdDelegate z przykładowej sieci reklamowej do przekazywania komunikatów o błędach i stanie:

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

Porównanie nakładki w aplikacji z aplikacją zewnętrzną

Po kliknięciu banera reklama może otworzyć się na pełnym ekranie lub w aplikacji zewnętrznej (np. Safari lub sklepie z aplikacjami). Wywołania zwrotne oprogramowania sprzęgającego do wywołania w tych 2 przypadkach są różne.

Jeśli kliknięcie banera spowoduje otwarcie nakładki pełnoekranowej, podczas jej prezentowania wywołaj funkcję adapterWillPresentFullScreenModal:. Gdy nakładka jest zamknięta, wywołaj zarówno adapterWillDismissFullScreenModal:, jak i adapterDidDismissFullScreenModal:.

Jeśli kliknięcie banera (lub kliknięcia pełnoekranowej nakładki) powoduje opuszczenie aplikacji przez użytkownika, wywołaj wywołanie zwrotne adapterWillLeaveApplication:.

Masz teraz działający adapter zapośredniczenia dla banerów. Pełną implementację interfejsu SampleAdapter znajdziesz na GitHub.

Implementowanie adaptera reklam pełnoekranowych

Implementacja adaptera w przypadku reklam pełnoekranowych jest podobna do banerów reklamowych. Metoda getInterstitial jest wywoływana natychmiast po zainicjowaniu adaptera. Ta metoda nie zwraca niczego. Adapter rozpocznie asynchroniczne pobieranie reklam przez sieć. Dopilnuj, aby adapter pełnił funkcję przedstawiciela, który będzie nasłuchiwał wywołań zwrotnych w Twoim pakiecie SDK. Jeśli Twój pakiet SDK nie obsługuje reklam pełnoekranowych, wywołaj metodę adapter:didFailAd: oprogramowania sprzęgającego w ten sposób:

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

Podobnie jak w przypadku MediationBannerAdapter, z oprogramowania sprzęgającego możesz otrzymywać informacje o wydawcy i kierowaniu reklam.

Powiadom zapośredniczenie

Dopilnuj, aby adapter wdrożył w Twojej sieci przedstawiciela reklam i przekierował odpowiednie wywołania zwrotne zdarzenia reklamowego przez oprogramowanie sprzęgające. W tabeli poniżej wyjaśniamy, kiedy wywoływać poszczególne metody przekazywania dostępu:

Metoda	Kiedy dzwonić
adapterDidReceiveInterstitial:	Żądanie reklamy pełnoekranowej zostało zrealizowane.
adapter:didFailInterstitial:	Nie udało się zrealizować żądania reklamy pełnoekranowej.
adapterDidGetAdClick:	Kliknięto reklamę pełnoekranową.
adapterWillPresentInterstitial:	Wyświetli się reklama pełnoekranowa.
adapterWillDismissInterstitial:	Reklama pełnoekranowa zostanie zamknięta.
adapterDidDismissInterstitial:	Reklama pełnoekranowa została zamknięta.
adapterWillLeaveApplication:	Aplikacja działa w tle lub zamyka się, ponieważ użytkownik kliknął reklamę, która powoduje uruchomienie innej aplikacji.

W poniższym przykładzie zaimplementowano interfejs SampleInterstitialAdDelegate przykładowej sieci reklamowej do przekazywania komunikatów o błędach i stanie:

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

Prezentuj reklamę pełnoekranową

Gdy adapter wywoła metodę adapterDidReceiveInterstitial, poczekaj, aż reklama pełnoekranowa zostanie pokazana, aż nastąpi wywołanie presentInterstitialFromRootViewController. To deweloper aplikacji decyduje, kiedy wyświetlić reklamę pełnoekranową, co może upłynąć kilka minut od jej otrzymania.

Oto implementacja presentInterstitialFromRootViewController: w przykładowej sieci reklamowej:

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

Adapter zapośredniczenia jest gotowy do obsługi reklam pełnoekranowych. Pełną implementację interfejsu SampleAdapter znajdziesz na GitHubie.

Najczęstsze pytania

Czy mam dołączyć adapter jako część biblioteki pakietu SDK czy jako oddzielną bibliotekę?

Zalecamy umieszczenie adaptera w bibliotece pakietu SDK, aby deweloperzy musieli odwoływać się do tylko jednej biblioteki, aby wykorzystać sieć.

Co zrobić, jeśli mój adapter obsługuje tylko banery reklamowe?

Jeśli adapter obsługuje tylko banery, skonfiguruj przekazywanie zdarzenia błędu do zapośredniczenia w przypadku żądań reklam pełnoekranowych:

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

Co zrobić, jeśli mój adapter obsługuje tylko reklamy pełnoekranowe?

Jeśli adapter obsługuje tylko reklamy pełnoekranowe, skonfiguruj przekazywanie zdarzenia błędu do zapośredniczenia w przypadku żądań banerów:

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