Eventos personalizados

Esta guía está dirigida a los editores que quieran añadir eventos personalizados de banner e intersticiales a la mediación de AdMob.

Gracias a los eventos personalizados, puedes incluir la vista que quieras en tu espacio publicitario. También puedes usarlos para monetizar tu aplicación con redes publicitarias que no sean directamente compatibles con la mediación. Se implementan a través de los protocolos GADCustomEventBanner o GADCustomEventInterstitial.

Requisitos previos

Antes de integrar eventos personalizados en un formato de anuncio, debes incorporar dicho formato a tu aplicación. Estas son las guías más importantes:

Red publicitaria de ejemplo

En esta guía descubrirás cómo se sirven anuncios de banner e intersticiales desde una red publicitaria de ejemplo mediante las clases de eventos personalizados SampleCustomEventBanner y SampleCustomEventInterstital. El SDK de la red publicitaria de ejemplo es un SDK ficticio, desarrollado para ilustrar el aspecto que tendría una implementación de un evento personalizado. Contiene clases representativas de las que ofrecen la mayoría de las redes publicitarias. Consulta la implementación completa del SDK de ejemplo para obtener más información acerca de estas clases.

En el siguiente ejemplo, primero crearás un evento personalizado de banner en la mediación de AdMob. Para ello, es necesario definir un evento personalizado que señale una clase específica de tu aplicación a través de la interfaz de AdMob y, luego, implementar un evento personalizado de banner para devolver una vista.

Definir un evento personalizado

Los eventos personalizados se deben definir en la interfaz de AdMob. En el artículo Añadir un evento personalizado encontrarás instrucciones sobre cómo desplazarte por la interfaz.

En esta captura de pantalla se muestran algunos ejemplos de ajustes de eventos personalizados:

La siguiente tabla te servirá de orientación cuando vayas a rellenar estos parámetros.

Nombre de clase

Escribe el nombre completo de la clase que implementa el evento personalizado.

Si la clase está implementada en Swift, debes añadir al nombre de la clase un prefijo que indique el módulo de la aplicación o el framework (por ejemplo, nombreAplicación.nombreClase).

Es necesario indicar el nombre del destino si tienes varios destinos en el proyecto o si el nombre de proyecto es diferente del nombre del destino. Con el nombre de destino, el aspecto sería el siguiente: nombreAplicación_nombreDestino.nombreClase. Además, recuerda sustituir por guiones bajos cualquier carácter no alfanumérico, como los guiones.

Si necesitas más detalles, consulta este ejemplo.

Etiqueta Introduce un nombre descriptivo para el evento.
Parámetro Si quieres transferir un argumento al evento personalizado, introduce la cadena correspondiente.

Solicitar un banner

En las solicitudes de banner de los eventos personalizados, se realiza una llamada al método requestBannerAd:parameter:label:request: inmediatamente después de instanciar la clase de evento personalizado. Este método no devuelve nada, ya que se presupone que el evento personalizado obtendrá el anuncio de forma asíncrona a través de la red. El evento personalizado debe actuar como delegado del SDK para recibir las retrollamadas.

Si el SDK no es compatible con el tamaño de anuncio indicado o con los anuncios de banner, realiza una llamada al método customEventBanner:didFailAd: del delegado de evento personalizado. Los parámetros serverParameter y serverLabel se corresponden con los campos de parámetros y de etiquetas definidos al crear un evento personalizado en la interfaz de AdMob.

Este es un ejemplo de implementación de requestBannerAd:parameter:label:request: a través de la red publicitaria de ejemplo:

Swift

func requestBannerAd(adSize: GADAdSize, parameter serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  // Create a banner view with the appropriate size.
  bannerAd = SampleBanner(frame: CGRectMake(
      0, 0, adSize.size.width, adSize.size.height))
  bannerAd.delegate = self
  bannerAd.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  bannerAd.fetchAd(adRequest)
}

Objective‑C

- (void)requestBannerAd:(GADAdSize)adSize
              parameter:(NSString *)serverParameter
                  label:(NSString *)serverLabel
                request:(GADCustomEventRequest *)request {
  // Create the bannerView with the appropriate size.
  self.bannerAd =
      [[SampleBanner alloc] initWithFrame:CGRectMake(0,
                                                     0,
                                                     adSize.size.width,
                                                     adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.bannerAd fetchAd:adRequest];
}

Enviar extras de la red publicitaria para las solicitudes de eventos personalizados

Para enviar extras de la red publicitaria junto con la solicitud que debe gestionar el evento personalizado, debes utilizar la función GADRequest registerAdNetworkExtras:. Crea una instancia de GADCustomEventExtras (que se ajuste al protocolo GADAdNetworkExtras) para que se rellene una propiedad GADCustomEventRequest.additionalParameters. Para transferir los extras, realiza una llamada a GADCustomEventExtras setExtras:forLabel: y transfiere los extras con formato de diccionario, así como la etiqueta del evento personalizado que has definido en la interfaz de AdMob.

En este fragmento de código puedes ver cómo se transfiere un parámetro SampleExtra para nuestra etiqueta SampleCustomEvent, que hemos definido anteriormente:

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective‑C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

Si no registras una instancia de GADCustomEventExtras para una solicitud de evento personalizado, la propiedad additionalParameters de GADCustomEventRequest será nil.

Notificar la mediación de AdMob

Implementa el agente de escucha de anuncios en tu red e invoca las retrollamadas pertinentes en el delegado del evento personalizado para devolver mensajes a la mediación. En el siguiente fragmento, se implementa la interfaz SampleBannerAdDelegate de la red publicitaria de ejemplo para poder enviar dichos mensajes:

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when banner ad has loaded.
func bannerDidLoad(banner: SampleBanner!) {
  delegate.customEventBanner(self, didReceiveAd: banner)
}

// Sent when banner has failed to load.
func banner(banner: SampleBanner!, didFailToLoadAdWithErrorCode error: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventBanner.customEventErrorDomain,
      code: error.rawValue, userInfo: nil)
  delegate.customEventBanner(self, didFailAd: nsError)
}

// Sent when a banner is clicked and an external application is launched
func bannerWillLeaveApplication(banner: SampleBanner!) {
  delegate.customEventBannerWasClicked(self)
  delegate.customEventBannerWillLeaveApplication(self)
}

Objective‑C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when banner ad has loaded.
- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.delegate customEventBanner:self didReceiveAd:banner];
}

// Sent when banner has failed to load.
- (void)banner:(SampleBanner *)banner
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventBanner:self didFailAd:error];
}

// Sent when a banner is clicked and an external application is launched.
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.delegate customEventBannerWasClicked:self];
  [self.delegate customEventBannerWillLeaveApplication:self];
}

Para obtener más información, consulta la implementación de ejemplo de un banner de evento personalizado.

Evento personalizado intersticial

Los eventos personalizados intersticiales se implementan de forma similar a los eventos personalizados de banner. La diferencia principal es que la clase de evento personalizado intersticial que crees debe implementar el protocolo GADCustomEventInterstitial en lugar de GADCustomEventBanner.

Definir un evento personalizado

Los eventos personalizados se deben definir en la interfaz de AdMob. En el artículo Añadir un evento personalizado encontrarás instrucciones sobre cómo desplazarte por la interfaz.

En esta captura de pantalla se muestran algunos ejemplos de ajustes de eventos personalizados:

La siguiente tabla te servirá de orientación cuando vayas a rellenar estos parámetros.

Nombre de clase

Escribe el nombre completo de la clase que implementa el evento personalizado.

Si tu clase está implementada en Swift, debes añadir al nombre de la clase un prefijo que indique el módulo de la aplicación o el framework (por ejemplo, nombreAplicación.nombreClase).

Es necesario indicar el nombre del destino si tienes varios destinos en el proyecto o si el nombre de proyecto es diferente del nombre del destino. Con el nombre de destino, el aspecto sería el siguiente: nombreAplicación_nombreDestino.nombreClase. Además, recuerda sustituir por guiones bajos cualquier carácter no alfanumérico, como los guiones.

Para obtener más información, consulta este ejemplo.

Etiqueta Introduce un nombre descriptivo para el evento.
Parámetro Si quieres transferir un argumento al evento personalizado, introduce la cadena correspondiente.

Solicitar un intersticial

En las solicitudes de intersticiales de los eventos personalizados, se realiza una llamada al método requestInterstitialAdWithParameter:label:request: inmediatamente después de instanciar la clase de evento personalizado. Este método no devuelve nada, ya que se presupone que el evento personalizado obtendrá el anuncio de forma asíncrona a través de la red.

El evento personalizado debe actuar como delegado del SDK para recibir las retrollamadas. Los parámetros serverParameter y serverLabel se corresponden con los campos de parámetros y de etiquetas definidos al crear un evento personalizado en la interfaz de AdMob.

Este es un ejemplo de implementación de requestInterstitialAdWithParameter:label:request: a través de la red publicitaria de ejemplo:

Swift

func requestInterstitialAdWithParameter(serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  interstitial = SampleInterstitial()
  interstitial.delegate = self
  interstitial.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  interstitial.fetchAd(adRequest)
}

Objective‑C

- (void)requestInterstitialAdWithParameter:(NSString *)serverParameter
                                     label:(NSString *)serverLabel
                                   request:(GADCustomEventRequest *)request {
  self.interstitial = [[SampleInterstitial alloc] init];
  self.interstitial.delegate = self;
  self.interstitial.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.interstitial fetchAd:adRequest];
}

El protocolo de eventos personalizados GADCustomEventInterstitial requiere que implementes el método presentFromRootViewController:. La mediación invoca dicho método de esta manera cuando indicas al SDK de anuncios para móviles que muestre el intersticial:

Swift

func presentFromRootViewController(rootViewController: UIViewController!) {
  if interstitial.interstitialLoaded {
    interstitial.show()
  }
}

Objective‑C

- (void)presentFromRootViewController:(UIViewController *)rootViewController {
  if ([self.interstitial isInterstitialLoaded]) {
    [self.interstitial show];
  }
}

Enviar extras de la red publicitaria para las solicitudes de eventos personalizados

Para enviar extras de la red publicitaria junto con la solicitud que debe gestionar el evento personalizado, debes utilizar la función GADRequest registerAdNetworkExtras:. Crea una instancia de GADCustomEventExtras (que se ajuste al protocolo GADAdNetworkExtras) para que se rellene una propiedad GADCustomEventRequest.additionalParameters. Para transferir los extras, realiza una llamada a GADCustomEventExtras setExtras:forLabel: y transfiere los extras con formato de diccionario, así como la etiqueta del evento personalizado que has definido en la interfaz de AdMob.

En este fragmento de código puedes ver cómo se transfiere un parámetro SampleExtra para nuestra etiqueta SampleCustomEvent, que hemos definido anteriormente:

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective‑C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

Si no registras una instancia de GADCustomEventExtras para una solicitud de evento personalizado, la propiedad additionalParameters de GADCustomEventRequest será nil.

Notificar la mediación de AdMob

Al igual que harías con un evento personalizado de banner, implementa el agente de escucha de anuncios de tu red para devolver mensajes a la mediación. En el siguiente ejemplo se muestra la implementación de la interfaz SampleInterstitialAdDelegate de la red publicitaria de ejemplo:

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when an interstitial ad has loaded.
func interstitialDidLoad(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidReceiveAd(self)
}

// Sent when interstitial ad has failed to load.
func interstitial(interstitial: SampleInterstitial!,
    didFailToLoadAdWithErrorCode errorCode: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventInterstitial.customEventErrorDomain,
      code: errorCode.rawValue, userInfo: nil)
  delegate.customEventInterstitial(self, didFailAd: nsError)
}

// Sent when an interstitial is about to be shown.
func interstitialWillPresentScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillPresent(self)
}

// Sent when an interstitial is about to be dismissed.
func interstitialWillDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillDismiss(self)
}

// Sent when an interstitial has been dismissed.
func interstitialDidDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidDismiss(self)
}

// Sent when an interstitial is clicked and an external application is launched.
func interstitialWillLeaveApplication(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWasClicked(self)
  delegate.customEventInterstitialWillLeaveApplication(self)
}

Objective‑C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when an interstitial ad has loaded.
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidReceiveAd:self];
}

// Sent when an interstitial ad has failed to load.
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventInterstitial:self didFailAd:error];
}

// Sent when an interstitial is about to be shown.
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillPresent:self];
}

// Sent when an interstitial is about to be dismissed.
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillDismiss:self];
}

// Sent when an interstitial has been dismissed.
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidDismiss:self];
}

// Sent when an interstitial is clicked and an external application is launched.
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWasClicked:self];
  [self.delegate customEventInterstitialWillLeaveApplication:self];
}

El envío de mensajes a la mediación permite que prosiga el flujo de mediación.

Para obtener más información, consulta este ejemplo de implementación de un evento intersticial personalizado.