Configurer des annonces à l'ouverture d'une application

Les annonces à l'ouverture d'une application s'affichent lorsque les utilisateurs ouvrent votre application ou y reviennent. Ils peuvent les fermer à tout moment. Pour monétiser l'écran de chargement de votre application, utilisez des annonces à l'ouverture d'une application. Pour en savoir plus, consultez Conseils et bonnes pratiques concernant les annonces à l'ouverture d'une application.

Ce guide explique comment intégrer des annonces à l'ouverture d'une application dans une application React Native.

Prérequis

Avant de continuer, procédez comme suit :

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

Comprendre le préchargement des annonces

Le préchargement des annonces dans Google Mobile Ads SDK for React Native automatise le chargement et la mise en cache des annonces.

Le préchargement des annonces offre les avantages suivants :

  • Gestion des références : conserve les références jusqu'à ce que les annonces soient diffusées.
  • Rechargement automatique : charge une nouvelle annonce lorsqu'une annonce est récupérée à partir du cache.
  • Nouvelles tentatives gérées : charge une nouvelle annonce lorsqu'une annonce ne se charge pas.
  • Gestion de l'expiration : actualise les annonces avant leur expiration.
  • Optimisation du cache : optimise l'ordre du cache pour diffuser l'annonce ayant la priorité la plus élevée.

Pour charger des annonces manuellement, consultez le guide Charger une seule annonce à l'ouverture d'une application.

Démarrer le préchargement

Pour commencer à précharger des annonces, appelez la méthode AppOpenAdPreloader.start et transmettez votre valeur preloadId, vos paramètres de configuration et vos rappels d'événements pour surveiller les changements d'état du tampon :

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 est une chaîne qui identifie de manière unique une configuration de préchargement d'annonces. Si l'adUnitId n'est utilisé que pour une seule configuration de préchargement dans votre application, vous pouvez utiliser cet ID de bloc d'annonces comme ID de préchargement. Si votre application nécessite plusieurs préchargeurs pour le même ID de bloc d'annonces, transmettez des chaînes distinctes pour chaque ID de préchargement.

Lorsque votre application interroge une annonce préchargée à partir du tampon, Google Mobile Ads SDK for React Native demande une annonce de remplacement en arrière-plan pour remplir à nouveau le tampon. S'il ne reste aucune annonce préchargée dans le tampon, Google Mobile Ads SDK for React Native appelle le rappel onAdsExhausted.

Limites du cache de préchargement

Google Mobile Ads SDK for React Native applique une limite à l'échelle de l'application sur le nombre total d'annonces préchargées :

  • Limite par défaut : Google conserve un maximum de six annonces préchargées en mémoire.
  • Nous vous recommandons de conserver une taille de tampon de deux pour chaque ID de préchargement.

Si votre application atteint la limite définie pour l'ensemble de l'application, les requêtes en arrière-plan pour les annonces préchargées sont mises en veille jusqu'à ce que les annonces existantes soient interrogées et affichées ou détruites.

Interroger et diffuser l'annonce

Pour vérifier si des annonces préchargées sont disponibles et récupérer une instance d'annonce, appelez la méthode AppOpenAdPreloader.pollAd.

Pour écouter les événements de présentation en plein écran, enregistrez des rappels sur la propriété adEventCallback de l'instance AppOpenAd renvoyée avant d'appeler la méthode 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();
}

Pour libérer de la mémoire et des ressources, appelez la méthode ad.destroy dans les rappels onAdDismissedFullScreenContent et onAdFailedToShowFullScreenContent lorsqu'un utilisateur ferme une annonce ou que l'annonce ne s'affiche pas.

Lire les informations de la réponse

Pour inspecter les détails de l'annonce préchargée suivante sans la supprimer du cache, appelez la méthode 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;
}

Gérer les annonces à l'ouverture d'une application avec un gestionnaire au niveau de l'application

Étant donné que les annonces à l'ouverture d'une application sont présentées de manière globale lors du lancement de l'application et des transitions au premier plan, nous vous recommandons de gérer l'état du cycle de vie du préchargeur dans un gestionnaire au niveau de l'application en dehors de l'arborescence des composants React.

L'utilisation d'un gestionnaire au niveau de l'application offre plusieurs avantages clés :

  • Maintient l'état du préchargeur indépendamment de la navigation sur l'écran individuel et du cycle de vie des composants.
  • Centralise les rappels d'événements d'annonce, le suivi de l'état et le nettoyage dans une seule instance partagée dans votre application.
  • Contrôle le moment où les événements de premier plan sont écoutés, ce qui évite les présentations en double lors de la fermeture de l'annonce.

L'exemple suivant implémente un gestionnaire au niveau de l'application à l'aide de l'objet 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();
  }
}

Écouter les événements de mise au premier plan de l'application

Pour diffuser des annonces lorsque votre application revient au premier plan, enregistrez un écouteur change sur le module AppState dans le composant racine de votre application, tel que App.tsx. Vérifiez quand l'état passe à active. Par exemple, appelez la méthode start sur votre instance de gestionnaire d'annonces dans le composant App.tsx.

La présentation d'annonces en superposition ou de pages de destination, comme l'affichage d'annonces en plein écran ou l'appui sur une bannière, fait passer votre application en arrière-plan. Lorsque l'utilisateur revient dans votre application, celle-ci reçoit un nouvel événement d'état active. Pour éviter une présentation d'annonce involontaire ou une boucle dans laquelle le retour d'une annonce présente une annonce à l'ouverture de l'application à partir du cache, procédez comme suit :

  1. Supprimez l'écouteur d'événements AppState avant de présenter une annonce en plein écran.
  2. Pour vous assurer que l'écoute reprend, que l'utilisateur ferme l'annonce ou que l'annonce ne s'affiche pas, ajoutez à nouveau l'écouteur d'événements AppState dans les rappels onAdDismissedFullScreenContent et onAdFailedToShowFullScreenContent.

Pour obtenir un exemple complet de contrôle de la mise en pause et de la reprise des écouteurs d'événements de premier plan, consultez l'implémentation de AppOpenAdManager.

En savoir plus sur les démarrages à froid et les écrans de chargement

Un démarrage à froid se produit lorsque votre application démarre de zéro, par exemple lorsqu'un utilisateur l'ouvre pour la première fois ou après que l'appareil l'a fermée pour libérer de la mémoire. Lors d'un démarrage à froid, vous ne disposez pas d'une annonce à l'ouverture d'une application précédemment chargée à afficher ensuite.

En raison des délais de demande d'annonce, vos utilisateurs peuvent interagir avec votre application avant qu'une annonce ne s'affiche. Diffusez des annonces à l'ouverture d'une application lors des démarrages à froid uniquement à partir d'un écran de chargement pendant le chargement des composants de l'application. Si le chargement des éléments se termine et que l'utilisateur accède au contenu principal avant le chargement de l'annonce, ne diffusez pas l'annonce.

Effectuer un nettoyage des ressources

Lorsque le préchargement n'est plus nécessaire pour un écran ou un ID de bloc d'annonces (par exemple, lorsque vous quittez un écran qui précharge des annonces), appelez la méthode AppOpenAdPreloader.destroy pour libérer les ressources du préchargeur et éviter de conserver des objets d'annonce inutilisés en mémoire :

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

En plus de détruire la file d'attente du préchargeur, veillez à détruire les instances d'annonces interrogées individuelles lorsqu'un utilisateur ferme une annonce ou que l'annonce ne s'affiche pas. Pour en savoir plus, consultez Interroger et diffuser l'annonce.

Voir l'exemple complet

L'exemple de composant suivant démarre le préchargement lors de l'installation, suit le nombre d'annonces disponibles et fournit des commandes pour afficher les annonces préchargées à l'ouverture de l'application :

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>
  );
}

Remplacez les éléments suivants :

  • APP_OPEN_AD_UNIT_ID par l'ID de votre bloc d'annonces.
  • PRELOAD_ID par l'ID de votre préchargeur.

Étapes suivantes

Après avoir intégré les annonces à l'ouverture d'une application, explorez les sujets suivants :