Configura anuncios recompensados

Selecciona la plataforma: Android iOS Unity Flutter Android (heredado)

Los anuncios recompensados te permiten recompensar a los usuarios con elementos integrados en una app cuando interactúan con encuestas, anuncios con juegos y anuncios de video.

En esta guía, se explica cómo integrar anuncios 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 recompensados de prueba ca-app-pub-3940256099942544/5224354917.
    • Al compilar y verificar 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 GMA Next-Gen SDK, consulta Habilita los anuncios de prueba.

Información sobre la precarga de anuncios (beta)

La precarga de anuncios en GMA Next-Gen SDK automatiza la carga y el almacenamiento en caché de 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 uno no se carga.
  • Control de vencimiento: Actualiza los anuncios antes de que venzan.
  • Optimización de la caché: optimiza el orden de la caché para publicar el anuncio de mayor prioridad.

Comienza a precargar anuncios

Para comenzar a precargar anuncios, llama al método start una vez cuando inicialices GMA Next-Gen SDK. Después de llamar al start método, 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 comenzar a precargar anuncios:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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 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.

La precarga de anuncios no admite el cambio de parámetros de segmentación ni solicitudes de anuncios. Si necesitas cambiar los parámetros de segmentación entre solicitudes, usa la carga única.

Obtén y muestra los anuncios precargados

Antes de mostrar el anuncio, llama al método pollAd. No almacenes el objeto de anuncio precargado. Cuando llamas al pollAd método, 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.

Cuando tengas un objeto de anuncio disponible, llama al método show para mostrar el anuncio. Usa un objeto de escucha de recompensas para controlar los eventos de recompensa. En el siguiente ejemplo, se muestra cómo recuperar y mostrar 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 = RewardedAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded ad is not available.")
    return
  }

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

Java

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

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

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

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

Cuando tu app llegue a una posición de anuncio y pueda llamar al método show, llama al método pollAd. No llames al método pollAd en las devoluciones de llamada de precarga ni después de verificar el método isAdAvailable para retener un anuncio. Si necesitas inspeccionar los metadatos del anuncio antes de mostrarlo, lee la información de la respuesta sin quitar el anuncio de la caché.

Escucha 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:

Kotlin

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

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

Para pasar el contexto del usuario y de la aplicación en las devoluciones de llamada de verificación del servidor (SSV), establece opciones de verificación en el objeto de anuncio antes de mostrar el anuncio. Debido a que las devoluciones de llamada de SSV llegan a tu servidor desde Google sin estado de sesión, adjunta las siguientes cadenas opcionales. Google reenvía estas cadenas sin cambios como parámetros de consulta firmados en la devolución de llamada de SSV.

  • Parámetro de consulta user_id: Identifica al usuario al que se le debe acreditar, como un ID de cuenta interno.
  • Parámetro de consulta custom_data: Transporta datos de la app, como la posición de la recompensa, el nivel del juego o un nonce generado por el servidor.

Si no estableces un valor, Google omite ese parámetro de consulta de 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:

Kotlin

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

Java

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

Reemplaza SAMPLE_CUSTOM_DATA_STRING por tus datos personalizados.

Punto clave: El parámetro de consulta custom_data está codificado con porcentaje. Antes de analizar el valor, decodifica la URL de la cadena en tu servidor y verifica la firma de la devolución de llamada antes de confiar en los parámetros de consulta user_id o custom_data.

Opcional: Escucha 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 registrar eventos de precarga de anuncios:

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

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

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

Cuando un anuncio no se carga, GMA Next-Gen SDK precarga automáticamente los anuncios y reintenta las solicitudes fallidas para las configuraciones precargadas. No invoques solicitudes de carga manual en las devoluciones de llamada de errores. En los métodos de devolución de llamada de eventos de precarga, no llames a los métodos pollAd, destroy ni start. Llamar a estos métodos en las devoluciones de llamada puede invocar bucles de carga recursivos.

Opcional: Verifica la disponibilidad de anuncios

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

Kotlin

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

Java

private boolean isAdAvailable(String adUnitId) {
  return RewardedAdPreloader.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 o disminuir la cantidad de anuncios que se almacenan en la memoria. Recomendamos un tamaño de búfer de dos anuncios precargados. Si la mayor parte de tu tráfico proviene de dispositivos con poca memoria, reduce el tamaño del búfer.

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

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);
RewardedAdPreloader.start(adUnitId, preloadConfig);

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 todas las unidades de anuncios y los IDs de precarga:

  • Límite predeterminado: Google almacena un máximo de seis anuncios precargados en la memoria. Este límite se comparte en todos los formatos y los IDs de precarga.
  • Recomendamos mantener un tamaño de búfer de dos para cada ID de precarga.

Opcional: Detén la precarga de los anuncios

Mantén la precarga activa mientras tu app publique anuncios. Durante este tiempo, no uses el método destroy. Si no necesitas volver a mostrar anuncios para un ID de precarga específico en la sesión, puedes detener la precarga de anuncios. Para dejar de cargar anuncios para un ID de precarga específico, llama al método destroy con un ID de precarga. Llamar al método destroy quita 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:

Kotlin

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

Java

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

Opcional: Lee la información de la respuesta

Lee la información de la respuesta del siguiente anuncio precargado sin quitar el anuncio de la caché. Si necesitas inspeccionar los metadatos del anuncio antes de mostrarlo, lee la información de la respuesta en lugar de llamar al método pollAd.

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

Kotlin

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

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

Java

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

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