Configura los anuncios recompensados

Los anuncios recompensados otorgan a los usuarios elementos integrados en la app por interactuar con anuncios de video, anuncios con juego y encuestas. Para obtener más información, consulta la descripción general de las unidades de anuncios recompensados.

Para eliminar la latencia de presentación y garantizar que haya un anuncio disponible cuando un usuario obtenga una recompensa, el Google Mobile Ads SDK for React Native usa la precarga de anuncios para administrar la carga en segundo plano, el almacenamiento en caché y la reposición del búfer.

En esta guía, se muestra cómo integrar anuncios recompensados en una app de React Native.

Requisitos previos

Antes de continuar, haz lo siguiente:

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

Información sobre la precarga de anuncios

La precarga de anuncios en Google Mobile Ads SDK for React Native automatiza la carga y el almacenamiento en caché de los anuncios.

La precarga de anuncios ofrece 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 puede cargar uno.
  • Administración de vencimientos: Actualiza los anuncios antes de que venzan.
  • Optimización de la caché: Optimiza el orden de la caché para publicar el anuncio con la prioridad más alta.

Para cargar anuncios de forma manual, consulta Carga un solo anuncio recompensado.

Comienza a precargar

Para comenzar a precargar anuncios, llama al método RewardedAdPreloader.start y pasa tu valor de preloadId, los parámetros de configuración y las devoluciones de llamada de eventos para supervisar los cambios de estado del búfer:

export function startRewardedAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`Rewarded ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload rewarded ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

Un ID de precarga es una cadena que identifica de forma inequívoca una configuración de precarga de anuncios. Si usas el ID de unidad de anuncios para una sola configuración de carga previa en tu app, puedes usar ese ID de unidad de anuncios como el ID de carga previa. Si tu app requiere varios precargadores para el mismo ID de unidad de anuncios, pasa cadenas distintas para cada ID de precarga.

Cuando tu app sondea un anuncio precargado del búfer, Google Mobile Ads SDK for React Native solicita un anuncio de reemplazo en segundo plano para volver a llenar el búfer. Si no quedan anuncios precargados en el búfer, Google Mobile Ads SDK for React Native invoca onAdsExhausted.

Límites de la caché de precarga

Google Mobile Ads SDK for React Native 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 almacena 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.
  • Tamaño de búfer recomendado: Dos para cada ID de carga previa.

Si tu app alcanza el límite de toda la app, las solicitudes en segundo plano de anuncios precargados se detendrán hasta que se sondeen los anuncios existentes de la caché o se destruyan. La carga previa también se detiene temporalmente mientras se muestra un anuncio de pantalla completa de forma activa.

Sondea y muestra el anuncio

Antes de mostrar un anuncio, llama al método RewardedAdPreloader.isAdAvailable para verificar que haya un anuncio disponible. Para recuperar el anuncio, llama al método RewardedAdPreloader.pollAd.

Para escuchar eventos de presentación, como descartes de anuncios o fallas de visualización, establece la propiedad adEventCallback en la instancia del anuncio antes de llamar al método show:

En el siguiente ejemplo, se verifica la disponibilidad de anuncios y se escuchan los eventos de presentación antes de mostrar el anuncio:

export function showPreloadedRewardedAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded ad available right now.');
    return;
  }

  const ad = RewardedAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded rewarded ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded rewarded ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded rewarded ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show(onRewardEarned);
}

Para liberar memoria y recursos, llama al método ad.destroy en las devoluciones de llamada onAdDismissedFullScreenContent y onAdFailedToShowFullScreenContent.

Lee la información de la respuesta

Para inspeccionar la información de respuesta del siguiente anuncio precargado sin quitarlo de la caché, llama al método RewardedAdPreloader.peekAdResponseInfo:

export function peekRewardedAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded rewarded ad response info:', responseInfo);
  }
  return responseInfo;
}

Si hay un anuncio disponible, el método peekAdResponseInfo devuelve un objeto ResponseInfo que contiene información sobre la fuente del anuncio cargado y los adaptadores de red.

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

Si tu app requiere parámetros de verificación personalizados, como un ID de usuario o metadatos de recompensa personalizados, en las devoluciones de llamada de la verificación del servidor (SSV), establece la propiedad serverSideVerificationOptions en la instancia de anuncio sondeada antes de llamar a show.

Los valores que establezcas se pasarán a los parámetros de consulta de la devolución de llamada de SSV:

  • userId: Se pasa al parámetro de consulta user_id para identificar al usuario.
  • customData: Se pasa al parámetro de consulta custom_data para reenviar metadatos personalizados.

En el siguiente ejemplo, se establece ServerSideVerificationOptions (customData y userId) en un objeto de anuncio recompensado antes de mostrar un anuncio:

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Limpia los recursos

Si ya no necesitas mostrar anuncios para un ID de carga previa específico durante el resto de la sesión, llama al método RewardedAdPreloader.destroy. Este proceso detiene la carga previa para ese ID de carga previa y libera de la memoria los anuncios precargados que no se usaron.

En el siguiente ejemplo, se detiene la precarga:

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

Después de que el usuario descarte el anuncio o este no se muestre, destruye las instancias individuales de anuncios sondeados. Para obtener más información, consulta Sondea y muestra el anuncio.

Observa el ejemplo completo

En el siguiente ejemplo, el componente inicia la precarga en el montaje, hace un seguimiento de los recuentos de anuncios disponibles y proporciona controles para mostrar anuncios recompensados precargados:

export function RewardedScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');
  const [reward, setReward] = useState<string | null>(null);

  const refreshAdCount = () => {
    const count = RewardedAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startRewardedAdPreloader(REWARDED_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Rewarded ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload rewarded ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for rewarded ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyRewardedAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        onAdDismissedFullScreenContent: () => {
          setStatus('Ad dismissed.');
        },
        onAdFailedToShowFullScreenContent: (error) => {
          setStatus(`Failed to show preloaded ad: ${error.message}`);
        },
      },
    );
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Rewarded Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Reemplaza lo siguiente:

  • REWARDED_AD_UNIT_ID por tu ID de unidad de anuncios
  • PRELOAD_ID por tu ID de precargador.

Próximos pasos

Después de integrar los anuncios recompensados, explora los siguientes temas: