Configura los anuncios para inicio de aplicación

Los anuncios para inicio de aplicación aparecen cuando los usuarios abren tu app o regresan a ella, y pueden cerrarlos en cualquier momento. Para monetizar la pantalla de carga de tu app, usa anuncios para inicio de aplicación. Para obtener más información, consulta la guía y las prácticas recomendadas de los anuncios para inicio de aplicación.

En esta guía, se explica cómo integrar anuncios de aplicación abierta en una app de React Native.

Requisitos previos

Antes de continuar, haz lo siguiente:

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

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 la guía Carga un solo anuncio para inicio de aplicación.

Comienza a precargar

Para comenzar a precargar anuncios, llama al método AppOpenAdPreloader.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 startAppOpenAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = AppOpenAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`App open ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload app open ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('App open ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

Un preloadId es una cadena que identifica de forma inequívoca una configuración de precarga de anuncios. Si el adUnitId se usa solo para una 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 la devolución de llamada onAdsExhausted.

Límites de la caché de precarga

Google Mobile Ads SDK for React Native aplica un límite en toda la app para la cantidad total de anuncios precargados:

  • Límite predeterminado: Google almacena un máximo de seis anuncios precargados en la memoria.
  • Te recomendamos que mantengas un tamaño de búfer de 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 detienen hasta que se sondean y se muestran o destruyen los anuncios existentes.

Sondea y muestra el anuncio

Para verificar si hay anuncios precargados disponibles y recuperar una instancia de anuncio, llama al método AppOpenAdPreloader.pollAd.

Para escuchar eventos de presentación de pantalla completa, registra devoluciones de llamada en la propiedad adEventCallback de la instancia AppOpenAd devuelta antes de llamar al método show:

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

Para liberar memoria y recursos, llama al método ad.destroy en las devoluciones de llamada onAdDismissedFullScreenContent y onAdFailedToShowFullScreenContent cuando un usuario descarte un anuncio o este no se muestre.

Lee la información de la respuesta

Para inspeccionar los detalles del siguiente anuncio precargado sin quitarlo de la caché, llama al método AppOpenAdPreloader.peekAdResponseInfo:

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

Administra los anuncios para inicio de aplicación con un administrador a nivel de la app

Debido a que los anuncios para inicio de aplicación se presentan de forma global durante el inicio de la app y las transiciones a primer plano, te recomendamos que administres el estado del ciclo de vida del precargador en un administrador a nivel de la app fuera del árbol de componentes de React.

Usar un administrador a nivel de la app ofrece varias ventajas clave:

  • Mantiene el estado del precargador independiente de la navegación de pantalla individual y el ciclo de vida del componente.
  • Centraliza las devoluciones de llamada de eventos de anuncios, el seguimiento de estado y la limpieza en una sola instancia compartida en toda tu app.
  • Controla cuándo se escuchan los eventos en primer plano, lo que evita que se muestren anuncios duplicados cuando se descartan.

En el siguiente ejemplo, se implementa un administrador a nivel de la app con el objeto AppOpenAdPreloader:

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

Escucha los eventos de app en primer plano

Para mostrar anuncios gráficos cuando tu app vuelva al primer plano, registra un objeto de escucha change en el módulo AppState del componente raíz de tu app, como App.tsx. Verifica cuándo el estado cambia a active. Por ejemplo, llama al método start en tu instancia del administrador de anuncios en el componente App.tsx.

Cuando se presentan superposiciones de anuncios o páginas de destino, como cuando se muestran anuncios de pantalla completa o se presiona un anuncio de banner, tu aplicación pasa a segundo plano. Cuando el usuario regresa a tu aplicación, esta recibe un nuevo evento de estado active. Para evitar una presentación de anuncios no deseada o un bucle en el que, al volver de un anuncio, se presente un anuncio para inicio de aplicación de la caché, haz lo siguiente:

  1. Quita el objeto de escucha de eventos AppState antes de presentar un anuncio de pantalla completa.
  2. Para asegurarte de que la escucha se reanude si un usuario descarta el anuncio o si este no se muestra, vuelve a agregar el objeto de escucha de eventos AppState en las devoluciones de llamada onAdDismissedFullScreenContent y onAdFailedToShowFullScreenContent.

Para ver un ejemplo completo de cómo controlar cuándo se pausan y reanudan los objetos de escucha de eventos en primer plano, consulta la implementación de AppOpenAdManager.

Más información sobre los inicios en frío y las pantallas de carga

Un inicio en frío se produce cuando tu app se inicia desde cero, por ejemplo, cuando un usuario la abre por primera vez o después de que el dispositivo la cierra para liberar memoria. Durante un inicio en frío, no tienes un anuncio para inicio de aplicación cargado previamente para mostrar a continuación.

Debido a las demoras en las solicitudes de anuncios, es posible que los usuarios interactúen con tu app antes de que aparezca un anuncio. Muestra anuncios para inicio de aplicación en los inicios en frío solo desde una pantalla de carga mientras se cargan los recursos de la app. Si los recursos terminan de cargarse y el usuario llega al contenido principal antes de que se cargue el anuncio, no lo muestres.

Limpia los recursos

Cuando ya no se requiera la carga previa para un ID de unidad de anuncios o una pantalla, como cuando se sale de una pantalla que carga anuncios previamente, llama al método AppOpenAdPreloader.destroy para liberar los recursos del cargador previo y evitar que se retengan objetos de anuncios sin usar en la memoria:

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

Además de destruir la cola del precargador, asegúrate de destruir las instancias de anuncios sondeados individuales cuando un usuario descarta un anuncio o este no se muestra. Para obtener más detalles, 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 los anuncios para inicio de aplicación precargados:

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Reemplaza lo siguiente:

  • APP_OPEN_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 para inicio de aplicación, explora los siguientes temas: