Precarga de anuncios (beta)

Selecciona la plataforma: Android iOS Unity Android (Legacy)

La precarga de anuncios es una función de carga de anuncios administrada por Google en GMA Next-Gen SDK que administra la carga y el almacenamiento en caché de anuncios en tu nombre. La precarga de anuncios requiere un cambio en la forma en que administras la carga de anuncios. Para optimizar el rendimiento con la precarga de anuncios, inhabilita el almacenamiento en caché personalizado y delega esa responsabilidad a GMA Next-Gen SDK.

La precarga de anuncios ofrece los siguientes beneficios en comparación con la carga manual de anuncios:

  • Administración de referencias: Almacena los anuncios cargados para que no tengas que mantener las referencias hasta que estés listo para mostrarlos.
  • Recarga automática: Carga automáticamente un anuncio nuevo cuando sacas uno de la caché.
  • Reintentos administrados: Reintenta automáticamente las solicitudes fallidas con la retirada exponencial.
  • Control de vencimiento: Actualiza automáticamente los anuncios antes de que venzan (por lo general, después de una hora).
  • Optimización de la caché: Si usas un tamaño de caché superior a uno, GMA Next-Gen SDK optimiza el orden de la caché para publicar el mejor anuncio.

En esta guía, se explica cómo configurar los anuncios para la precarga, verificar su disponibilidad y mostrar los anuncios precargados.

Requisitos previos

Antes de continuar con el instructivo, tienes que completar las siguientes tareas:

Comienza a precargar anuncios

Para comenzar a precargar anuncios, llama a startPreload(). Llama a este método solo una vez por ID de precarga. Te recomendamos que llames al método cuando comience la sesión de la app. Después de llamar a startPreload(), GMA Next-Gen SDK precarga automáticamente los anuncios y reintenta las solicitudes fallidas para esos IDs de precarga.

En el siguiente ejemplo, se comienza a precargar anuncios:

Kotlin

private fun startPreloading(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void startPreloading(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Obtén y muestra los anuncios precargados

Cuando se usa la precarga de anuncios, GMA Next-Gen SDK almacena los anuncios en caché. Cuando quieras mostrar un anuncio, llama a pollAd(). GMA Next-Gen SDK recupera el anuncio disponible y precarga automáticamente el siguiente anuncio en segundo plano.

En el siguiente ejemplo, se recupera y se muestra un anuncio precargado:

Kotlin

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = InterstitialAdPreloader.pollAd(adUnitId)

  // Interact with the ad object as needed.
  ad?.apply {
    Log.d(TAG, "Interstitial ad response info: ${this.getResponseInfo()}")
    this.adEventCallback =
      object : InterstitialAdEventCallback {
        override fun onAdImpression() {
          Log.d(TAG, "Interstitial ad recorded an impression.")
        }

        override fun onAdPaid(value: AdValue) {
          Log.d(TAG, "Interstitial ad onPaidEvent: ${value.valueMicros} ${value.currencyCode}")
        }
      }

    // Show the ad.
    ad.show(activity)
  }
}

Java

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final InterstitialAd ad = InterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad != null) {
    Log.d(TAG, "Interstitial ad response info: " + ad.getResponseInfo());
    ad.setAdEventCallback(
        new InterstitialAdEventCallback() {
          @Override
          public void onAdImpression() {
            Log.d(TAG, "Interstitial ad recorded an impression.");
          }

          @Override
          public void onAdPaid(AdValue value) {
            Log.d(
                TAG,
                "Interstitial ad onPaidEvent: "
                    + value.getValueMicros()
                    + " "
                    + value.getCurrencyCode());
          }
        });

    // Show the ad.
    ad.show(activity);
  }
}

Obtén metadatos de anuncios precargados

Para obtener metadatos de anuncios precargados, puedes buscar el objeto de información de respuesta del anuncio. Este proceso te permite inspeccionar los metadatos del anuncio sin quitarlo de la caché.

En el siguiente ejemplo, se buscan los metadatos de un anuncio precargado en el objeto de información de respuesta:

Kotlin

private fun peekAdResponseInfo(preloadId: String) {
  InterstitialAdPreloader.peekAdResponseInfo(preloadId)?.let {
    Log.d(TAG, "Peeked ad response ID: ${it.responseId}")
  }
}

Java

private void peekAdResponseInfo(String preloadId) {
  ResponseInfo responseInfo = InterstitialAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo != null) {
    Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());
  }
}

Verifica la disponibilidad de anuncios precargados

Para verificar la disponibilidad de anuncios, elige una de las siguientes opciones:

Obtén la disponibilidad de anuncios precargados

En el siguiente ejemplo, se verifica la disponibilidad de anuncios:

Kotlin

private fun isAdAvailable(adUnitId: String): Boolean {
  return InterstitialAdPreloader.isAdAvailable(adUnitId)
}

Java

private boolean isAdAvailable(String adUnitId) {
  return InterstitialAdPreloader.isAdAvailable(adUnitId);
}

Escucha la disponibilidad de anuncios precargados

Regístrate para recibir eventos de precarga y recibir notificaciones cuando los anuncios se precarguen correctamente, no se precarguen o se agote la caché de anuncios.

Los eventos de precarga están destinados a fines de estadísticas. Dentro de las devoluciones de llamada de eventos de precarga:

  • No llames a startPreload().
  • Evita llamar a pollAd() a menos que el anuncio se muestre de inmediato.

En el siguiente ejemplo, se registra para recibir eventos de anuncios:

Kotlin

private fun startPreloadingWithCallback(adUnitId: String) {
  val preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    object : PreloadCallback {
      override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
        Log.i(
          TAG,
          ("Interstitial preload ad $preloadId failed to load with error: ${adError.message}"),
        )
        // [Optional] Get the error response info for additional details.
        // val responseInfo = adError.responseInfo
      }

      override fun onAdsExhausted(preloadId: String) {
        Log.i(TAG, "Interstitial preload ad $preloadId is not available")
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
        Log.i(TAG, "Interstitial preload ad $preloadId is available")
      }
    }
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}

Java

private void startPreloadingWithCallback(String adUnitId) {
  PreloadCallback preloadCallback =
      // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
      new PreloadCallback() {
        @Override
        public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
          Log.e(
              TAG,
              String.format(
                  "Interstitial preload ad %s failed to load with error: %s",
                  preloadId, adError.getMessage()));
          // [Optional] Get the error response info for additional details.
          // ResponseInfo responseInfo = adError.getResponseInfo();
        }

        @Override
        public void onAdsExhausted(String preloadId) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is not available");
          // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
        }

        @Override
        public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
          Log.i(TAG, "Interstitial preload ad " + preloadId + " is available");
        }
      };

  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}

Detén la precarga de anuncios

Si no necesitas volver a mostrar anuncios para un ID de precarga en la sesión, puedes detener la precarga de anuncios. Para detener la precarga de anuncios para un ID de precarga específico, llama a destroy() con un ID de precarga. Para detener la precarga de todos los precargadores, llama a destroyAll().

Configura el tamaño del búfer

El tamaño del búfer controla la cantidad de anuncios precargados que se almacenan en la memoria. De forma predeterminada, Google optimiza el tamaño del búfer para equilibrar el consumo de memoria y la latencia de publicación de anuncios. Si tu app muestra anuncios antes de que se cargue el siguiente anuncio, puedes establecer un tamaño de búfer personalizado para aumentar la cantidad de anuncios que se conservan en la memoria. Te recomendamos un tamaño de búfer de dos o tres.

Límites de caché de precarga

GMA Next-Gen SDK aplica un límite en toda la app para la cantidad total de anuncios precargados en todos los IDs de precarga y bloques de anuncios:

  • Límite predeterminado: GMA Next-Gen SDK almacena un máximo de seis anuncios precargados en la memoria. Este límite se comparte en todos los formatos y IDs de precarga.
  • Te recomendamos que mantengas un tamaño de búfer de dos o tres por ID de precarga.

Kotlin

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 3)
  InterstitialAdPreloader.start(adUnitId, preloadConfig)
}

Java

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 3);
  InterstitialAdPreloader.start(adUnitId, preloadConfig);
}