Entwicklung des Ad Network Mediation-Adapters

Hinweis :Die Verwendung des Google Mobile Ads SDK in Verbindung mit den Vermittlungsdiensten unterliegt den Nutzungsbedingungen für die Vermittlung.

Dieser Leitfaden richtet sich an Werbenetzwerke, die einen Vermittlungsadapter erstellen möchten. Wenn Sie Publisher sind, lesen Sie die Anleitung zur Vermittlung für Publisher.

Ein Vermittlungsadapter stellt die Kommunikationsebene zwischen Ihrem Werbenetzwerk und der Google Mobile Ads Mediation dar. Adapter liefern Anzeigen aus Ihrem Werbenetzwerk und leiten relevante Anzeigenereignisse an AdMob weiter. Ein Adapter ist für die Implementierung des GADMAdNetworkAdapter-Protokolls verantwortlich, damit die erforderlichen Funktionen bereitgestellt werden.

Voraussetzungen

• Xcode 15.3 oder höher
• Bereitstellungsziel 8.0 oder höher
• Zusätzliche Header aus dem Ordner "Vermittlungsadapter" des Google Mobile Ads SDK für iOS

Damit zwischen Ihrem Werbenetzwerk und Google ein Vermittlungsadapter erstellt werden kann, muss eine entsprechende Geschäftsbeziehung bestehen.

Beispiel-Werbenetzwerk

In diesem Leitfaden wird gezeigt, wie Sie einen Adapter für das Sample Ad Network erstellen. Das Sample Ad Network SDK enthält Klassen, die repräsentativ für die von den meisten Werbenetzwerken angebotenen Klassen sind:

@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

Weitere Informationen zu diesen Klassen findest du unter Vollständiges Beispiel für die SDK-Implementierung.

Connector

Vermittlungsadapter interagieren über ein Objekt mit dem Google Mobile Ads SDK, das das GADMAdNetworkConnector-Protokoll implementiert. Ab jetzt nennen wir dieses Objekt den Connector. Der Connector stellt die erforderlichen Informationen für Anzeigenanfragen bereit und ermöglicht einen Rückruf bei Anzeigenereignissen und Nutzerinteraktionen an die Vermittlung. Der Connector wird den Vermittlungsadaptern bei der Initialisierung bereitgestellt. Richten Sie den Adapter so ein, dass der Connector in einer Instanzvariablen gespeichert wird:

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

Serverparameter

In Ihrem Werbenetzwerk werden wahrscheinlich Kennzeichnungen benötigt, um einen Publisher zu identifizieren. Für das Beispielwerbenetzwerk ist beispielsweise ein Anzeigenblock erforderlich. Diese erforderlichen Serverparameter werden über die Methode credentials an den Adapter übergeben, die eine NSDictionary mit Kennzeichnungen und entsprechenden Werten zurückgibt. Mit der folgenden Codezeile wird der Serverparameter ad_unit für das Beispielwerbenetzwerk vom Connector abgerufen:

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

Vermittlungsnetzwerk einrichten

Werbenetzwerke müssen AdMob über die erforderlichen Serverparameter informieren. So kann AdMob Ihr Werbenetzwerk im Frontend konfigurieren.

Wenn Sie Ihr Netzwerk für die Vermittlung im Frontend aktivieren, müssen Sie in AdMob Werte eingeben, die zur Instanziierung Ihres Adapters erforderlich sind. Im folgenden Screenshot sehen Sie, dass für Millennial Media eine Application Placement Identifier (APID) und für InMobi eine App-ID erforderlich ist.

Weitere Informationen zum Konfigurieren von Werbenetzwerken zur Vermittlung finden Sie in diesem Artikel.

Vermittlungsanzeigenanfrage stellen

Banneranfrage

Bei Anfragen für Vermittlungsbanner wird die Methode getBannerWithSize unmittelbar nach der Instanziierung des Adapters aufgerufen. Diese Methode gibt nichts zurück. Er signalisiert dem Adapter, dass er einen asynchronen Anzeigenabruf über das Netzwerk startet. Dein Adapter auf Callbacks für dein SDK warten lassen. Wenn Ihr SDK die angegebene Anzeigengröße nicht oder keine Banneranzeigen unterstützt, rufen Sie im Connector die Methode adapter:didFailAd: auf.

Eine Implementierung von getBannerWithSize für das Beispielwerbenetzwerk sieht so aus:

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

Zusätzliche Targeting-Parameter

Der Connector enthält einige allgemeine Targeting-Informationen, auf die Sie für die Anzeigenausrichtung zurückgreifen können:

• userKeywords
• testMode
• childDirectedTreatment

Vermittlungsextras

Mit Vermittlungsextras kann Ihr Werbenetzwerk zusätzliche Targeting-Parameter oder Eingaben unterstützen, die nicht von den zusätzlichen Anfrageparametern des Connectors abgedeckt werden. Diese Funktionalität kann über eine Klasse bereitgestellt werden, die das GADAdNetworkExtras-Protokoll implementiert. Im Folgenden wird die Klasse SampleAdNetworkExtras als Beispiel dargestellt:

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

@end

Publisher müssen beim Senden einer Anzeigenanfrage eine Instanz Ihrer abgeleiteten GADAdNetworkExtras übergeben. Auf diese Instanz Ihrer GADAdNetworkExtras-Unterklasse kann über den Connector zugegriffen werden. So können Sie Vermittlungsextras verwenden, wenn Sie eine Anzeigenanfrage für Ihr Netzwerk erstellen:

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

Damit auf die abgeleitete GADAdNetworkExtras-Klasse über den Connector zugegriffen werden kann, müssen Sie networkExtrasClass implementieren und Ihre GADAdNetworkExtras-Unterklasse zurückgeben:

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

Wenn Ihr Adapter keine Vermittlungsextras verwendet, gibt die networkExtrasClass-Methode Nil zurück.

Vermittlung benachrichtigen

Bitten Sie Ihren Adapter, den Anzeigen-Listener für Ihr Netzwerk zu implementieren und die relevanten Callbacks für Anzeigenereignisse über den Connector weiterzuleiten. In der folgenden Tabelle wird erläutert, wann die einzelnen Delegatmethoden aufgerufen werden sollten:

Methode	Wann Sie anrufen sollten
adapter:didReceiveAdView:	Die Banneranfrage war erfolgreich.
adapter:didFailAd:	Die Banneranfrage ist fehlgeschlagen.
adapterDidGetAdClick:	Auf das Banner wurde geklickt.
adapterWillPresentFullScreenModal:	Das Banner enthält ein In-App-Overlay.
adapterWillDismissFullScreenModal:	Das In-App-Overlay wird geschlossen.
adapterDidDismissFullScreenModal:	Das In-App-Overlay wurde geschlossen.
adapterWillLeaveApplication:	Die Anwendung wird im Hintergrund platziert oder beendet, weil der Nutzer auf eine Anzeige geklickt hat, durch die eine andere Anwendung gestartet wird.

Im folgenden Beispiel wird die SampleBannerAdDelegate-Schnittstelle des Beispielwerbenetzwerks implementiert, um Fehler- und Statusmeldungen weiterzuleiten:

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

Einführung von In-App-Overlays im Vergleich zu externen Apps

Wenn ein Banner angeklickt wird, öffnet die Anzeige möglicherweise ein Vollbild-Overlay oder eine externe App wie Safari oder der App Store. In diesen beiden Fällen unterscheiden sich die Connector-Callbacks.

Wenn durch den Klick auf ein Banner ein Vollbild-Overlay geöffnet wird, rufen Sie beim Präsentieren des Overlays adapterWillPresentFullScreenModal: auf. Wenn das Overlay geschlossen ist, rufen Sie sowohl adapterWillDismissFullScreenModal: als auch adapterDidDismissFullScreenModal: auf.

Wenn ein Klick auf ein Banner oder ein Klick auf ein Vollbild-Overlay dazu führt, dass der Nutzer die Anwendung verlässt, rufen Sie den adapterWillLeaveApplication:-Callback auf.

Sie haben jetzt einen funktionierenden Vermittlungsadapter für Banner. Eine vollständige Implementierung von SampleAdapter GitHub.

Interstitial-Adapter implementieren

Die Adapterimplementierung für Interstitial-Anzeigen ähnelt der von Banneranzeigen. Die Methode getInterstitial wird unmittelbar nach der Instanziierung des Adapters aufgerufen. Bei dieser Methode wird nichts zurückgegeben. Es wird erwartet, dass der Adapter einen asynchronen Anzeigenabruf über das Netzwerk startet. Ihr Adapter dient als Stellvertreter für Ihr SDK, der Callbacks abhört. Wenn Ihr SDK keine Interstitial-Anzeigen unterstützt, rufen Sie die Methode adapter:didFailAd: des Connectors so auf:

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

Genau wie bei MediationBannerAdapter können Sie vom Connector Publisher-Identifikatoren und Informationen zum Anzeigen-Targeting erhalten.

Vermittlung benachrichtigen

Bitten Sie Ihren Adapter, den Anzeigendelegat für Ihr Netzwerk zu implementieren und die relevanten Callbacks für Anzeigenereignisse über den Connector weiterzuleiten. In der folgenden Tabelle wird erläutert, wann die einzelnen Delegatmethoden aufgerufen werden sollten:

Methode	Wann Sie anrufen sollten
adapterDidReceiveInterstitial:	Die Interstitial-Anfrage wurde erfolgreich ausgeführt.
adapter:didFailInterstitial:	Die Interstitial-Anfrage ist fehlgeschlagen.
adapterDidGetAdClick:	Auf das Interstitial wurde geklickt.
adapterWillPresentInterstitial:	Das Interstitial wird eingeblendet.
adapterWillDismissInterstitial:	Das Interstitial wird geschlossen.
adapterDidDismissInterstitial:	Das Interstitial wurde geschlossen.
adapterWillLeaveApplication:	Die Anwendung wird im Hintergrund ausgeführt oder beendet, weil der Nutzer auf eine Anzeige geklickt hat, durch die eine andere App gestartet wird.

Im folgenden Beispiel wird die SampleInterstitialAdDelegate-Schnittstelle des Beispielwerbenetzwerks implementiert, um Fehler- und Statusmeldungen weiterzuleiten:

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

Interstitial präsentieren

Sobald der Adapter adapterDidReceiveInterstitial aufruft, soll das Interstitial erst dann eingeblendet werden, wenn presentInterstitialFromRootViewController aufgerufen wird. Der App-Entwickler entscheidet, wann die Interstitial-Anzeige eingeblendet wird. Dies kann einige Minuten nach Empfang dauern.

Hier ist eine Implementierung von presentInterstitialFromRootViewController: für das Beispielwerbenetzwerk:

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

Ihr Vermittlungsadapter kann jetzt Interstitial-Anzeigen verarbeiten. Eine vollständige Implementierung von SampleAdapter findest du auf GitHub.

Häufig gestellte Fragen

Soll ich den Adapter als Teil meiner SDK-Bibliothek oder als separate Bibliothek hinzufügen?

Wir empfehlen, den Adapter in Ihre SDK-Bibliothek aufzunehmen, damit Entwickler nur auf eine Bibliothek verweisen müssen, um Ihr Netzwerk einzubinden.

Was kann ich tun, wenn mein Adapter nur Banneranzeigen unterstützt?

Wenn Ihr Adapter nur Banner unterstützt, lassen Sie ihn ein Fehlerereignis an die Vermittlung für Interstitial-Anfragen weiterleiten:

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

Was mache ich, wenn mein Adapter nur Interstitial-Anzeigen unterstützt?

Wenn Ihr Adapter nur Interstitials unterstützt, lassen Sie ihn für Banneranfragen ein Fehlerereignis an die Vermittlung weiterleiten:

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