Configura anuncios intersticiales recompensados

Los anuncios intersticiales recompensados son un formato que te permite ofrecer recompensas por los anuncios que aparecen automáticamente durante las transiciones naturales de la app. A diferencia de los anuncios recompensados, no se requiere que los usuarios habiliten ninguna función para ver anuncios intersticiales recompensados.

En esta guía, se explica cómo integrar anuncios intersticiales recompensados en una app para Android.

Antes de comenzar

Antes de continuar, haz lo siguiente:

• Configura GMA Next-Gen SDK.
• Usa el ID de unidad de anuncios intersticiales recompensados de prueba /21775744923/example/rewarded-interstitial.
  • Al compilar y probar tu app, asegúrate de usar anuncios de prueba en vez de anuncios en producción activos. Si no usas el ID de unidad de anuncios de prueba, Google puede suspender tu cuenta.
  • Antes de publicar tu app, reemplaza este ID por tu ID de unidad de anuncios.
  • Para obtener detalles sobre los anuncios de prueba del GMA Next-Gen SDK, consulta Habilita los anuncios de prueba.

Información sobre la precarga de anuncios (beta)

La precarga de anuncios (beta) en GMA Next-Gen SDK automatiza la carga y el almacenamiento en caché de los anuncios.

La precarga de anuncios proporciona los siguientes beneficios:

• Administración de referencias: Mantiene las referencias hasta que se muestran los anuncios.
• Recarga automática: Carga un anuncio nuevo cuando se recupera uno de la caché.
• Reintentos administrados: Carga un anuncio nuevo cuando no se carga uno.
• Control de vencimiento: Actualiza los anuncios antes de que venzan.
• Optimización del caché: Optimiza el orden del caché para publicar el anuncio de mayor prioridad.

Comienza la precarga de anuncios

Para comenzar a precargar anuncios, llama al método start una vez al inicio de la app. Después de llamar al método start, GMA Next-Gen SDK precarga automáticamente los anuncios y reintenta las solicitudes fallidas para las configuraciones precargadas.

En el siguiente ejemplo, se muestra cómo iniciar la precarga de anuncios:

private fun startPreloading(adUnitId: String) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

private void startPreloading(String adUnitId) {
  // Call start() once after SDK initialization.
  // Preload only one ad unit per format to optimize performance.
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Reemplaza AD_UNIT_ID por tu ID de unidad de anuncios.

En el ejemplo anterior, se muestra cómo usar el ID de la unidad de anuncios como ID de precarga. Un ID de precarga es un identificador de cadena que creas para identificar una configuración de precarga de anuncios. Si tu app requiere varias configuraciones de segmentación para el mismo ID de unidad de anuncios, pasa un identificador de cadena personalizado.

Obtén y muestra el anuncio precargado

Cuando quieras mostrar un anuncio, llama al método pollAd. GMA Next-Gen SDK recupera un anuncio disponible y precarga automáticamente el siguiente anuncio en segundo plano. Si no hay anuncios disponibles, GMA Next-Gen SDK no devuelve ningún anuncio.

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

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

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Hasta que no esté listo para mostrar un anuncio, evita llamar al método pollAd. Para leer la información de la respuesta de solicitud de anuncio sin mostrarla, consulta Cómo leer la información de la respuesta.

Cómo detectar eventos de anuncios

Antes de mostrar el anuncio, escucha los eventos de anuncios. En el siguiente ejemplo, se registran devoluciones de llamada para eventos de anuncios:

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

Opcional: Valida las devoluciones de llamada de verificación del servidor (SSV)

Si tu app requiere datos adicionales en las devoluciones de llamada de verificación del servidor, usa la función de datos personalizados de los anuncios. Los servidores de anuncios de Google pasan cualquier valor de cadena establecido en un objeto de anuncio al parámetro de consulta custom_data de la devolución de llamada de SSV. Si no se establece ningún valor de datos personalizados, el valor del parámetro de consulta custom_data no estará presente en la devolución de llamada de SSV.

En el siguiente ejemplo, se establecen datos personalizados en un objeto de anuncio antes de mostrar el anuncio:

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

Reemplaza SAMPLE_CUSTOM_DATA_STRING por tus datos personalizados.

Opcional: Detecta eventos de precarga

Cuando comiences a precargar anuncios, 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.

En el siguiente ejemplo, se muestra cómo registrarse para recibir eventos de anuncios precargados:

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded 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, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded 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(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Cuando no se carga un anuncio, GMA Next-Gen SDK precarga automáticamente los anuncios y reintenta las solicitudes fallidas para las configuraciones precargadas.

Opcional: Verifica la disponibilidad de anuncios

Si necesitas saber si un anuncio está disponible, verifica su disponibilidad. En el siguiente ejemplo, se verifica si hay un anuncio precargado disponible:

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

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

Opcional: 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. Puedes establecer un tamaño de búfer personalizado para aumentar la cantidad de anuncios que se mantienen en la memoria. Recomendamos un tamaño de búfer de dos anuncios precargados.

En el siguiente ejemplo, se muestra cómo establecer un tamaño de búfer:

private fun setBufferSize(adUnitId: String) {
  val adRequest = AdRequest.Builder(adUnitId).build()
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)
}

private void setBufferSize(String adUnitId) {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  // Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
  RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);
}

Límites de caché de precarga

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

• Límite predeterminado: Google mantiene un máximo de seis anuncios precargados en la memoria. Este límite se comparte entre todos los formatos y los IDs de carga previa.
• Te recomendamos que mantengas un tamaño de búfer de dos para cada ID de carga previa.

[Opcional] Detén la precarga de los anuncios

Si no necesitas volver a mostrar anuncios para un ID de carga previa específico en la sesión, puedes detener la carga previa de anuncios. Para dejar de cargar anuncios para un ID de precarga específico, llama al método destroy con un ID de precarga. Si llamas al método destroy, se quitarán de la caché todos los anuncios precargados asociados con el ID de precarga.

En el siguiente ejemplo, se muestra cómo detener la precarga de anuncios:

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

Opcional: Lee la información de la respuesta

Lee la información de respuesta del siguiente anuncio precargado sin quitar el anuncio de la caché.

En el siguiente ejemplo, se muestra cómo leer la siguiente información de respuesta de solicitud de anuncio precargado:

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());