Configurer des annonces interstitielles avec récompense

Les interstitiels avec récompense sont un format d'annonce plein écran qui vous permet de proposer des éléments intégrés pour les annonces qui s'affichent entre les écrans ou les niveaux de jeu. Contrairement aux annonces avec récompense, les utilisateurs n'ont pas besoin d'accepter de les visionner. Pour en savoir plus, consultez les études de cas AdMob et la présentation des blocs d'annonces interstitielles avec récompense (bêta).

Pour éliminer la latence de présentation et s'assurer qu'une annonce est disponible lors d'une transition, Google Mobile Ads SDK for React Native utilise le préchargement des annonces pour gérer le chargement en arrière-plan, la mise en cache et le réapprovisionnement de la mémoire tampon.

Ce guide vous explique comment intégrer des interstitiels avec récompense avec préchargement des annonces dans une application React Native.

Prérequis

Avant de continuer, procédez comme suit :

Android 

ca-app-pub-3940256099942544/5354046379

iOS 

ca-app-pub-3940256099942544/6978759866

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 annonce lorsqu'une annonce est récupérée 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 Charger une seule annonce interstitielle avec récompense.

Démarrer le préchargement

Pour commencer à précharger des annonces, appelez la méthode RewardedInterstitialAdPreloader.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 startRewardedInterstitialAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedInterstitialAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(
          `Rewarded interstitial ad preloaded for ${event.preloadId}`,
        );
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error(
          'Failed to preload rewarded interstitial ad:',
          error.message,
        );
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded interstitial ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

preloadId est une chaîne qui identifie de manière unique une configuration de préchargement des annonces. Si vous utilisez un ID de bloc d'annonces pour une seule configuration de préchargement dans votre application, utilisez 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. Cette limite est partagée entre tous les formats et ID de préchargement.
  • Tampon recommandé : deux annonces préchargées pour chaque ID de préchargement.

Si votre application atteint la limite définie, les requêtes en arrière-plan pour les annonces préchargées sont suspendues jusqu'à ce que les annonces existantes soient interrogées à partir du cache ou détruites. Le préchargement est également mis en pause temporairement lorsqu'une annonce en plein écran est affichée à l'écran.

Interroger et diffuser l'annonce

Avant d'afficher une annonce, vérifiez qu'elle est disponible en appelant la méthode RewardedInterstitialAdPreloader.isAdAvailable. Pour récupérer l'annonce, appelez la méthode RewardedInterstitialAdPreloader.pollAd.

Pour diffuser une annonce, appelez la méthode show avec un rappel onUserEarnedReward pour accorder la récompense lorsque l'utilisateur a fini de regarder l'annonce. Pour écouter les événements de présentation, tels que les fermetures d'annonces ou les échecs d'affichage, définissez la propriété adEventCallback sur l'instance d'annonce avant d'appeler la méthode show.

L'exemple suivant vérifie la disponibilité de l'annonce et écoute les événements de présentation en plein écran avant de l'afficher :

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

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

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

  ad.show(onRewardEarned);
}

Pour libérer de la mémoire et des ressources, appelez la méthode ad.destroy dans les rappels onAdDismissedFullScreenContent et onAdFailedToShowFullScreenContent.

Lire les informations de la réponse

Pour inspecter les informations de réponse de l'annonce préchargée suivante sans la supprimer du cache, appelez la méthode RewardedInterstitialAdPreloader.peekAdResponseInfo :

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

Si une annonce est disponible, la méthode peekAdResponseInfo renvoie un objet ResponseInfo contenant des informations sur la source d'annonce chargée et les adaptateurs réseau.

Facultatif : Valider les rappels de validation côté serveur

Si votre application nécessite des paramètres de validation personnalisés, tels qu'un ID utilisateur ou des métadonnées de récompense personnalisées, dans les rappels de validation côté serveur, définissez la propriété serverSideVerificationOptions sur l'instance d'annonce interrogée avant d'appeler la méthode show.

Les valeurs que vous définissez sont transmises aux paramètres de requête de rappel SSV :

  • userId : transmet au paramètre de requête user_id pour identifier l'utilisateur.
  • customData : transmet au paramètre de requête custom_data pour transférer des métadonnées personnalisées.

L'exemple suivant définit ServerSideVerificationOptions (customData et userId) sur un objet d'annonce interstitielle avec récompense avant d'afficher une annonce :

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

Effectuer un nettoyage des ressources

Si vous n'avez plus besoin de diffuser d'annonces pour un ID de préchargement spécifique pendant le reste de la session, appelez la méthode RewardedInterstitialAdPreloader.destroy. Ce processus arrête le préchargement pour cet ID de préchargement et libère de la mémoire les annonces préchargées inutilisées.

L'exemple suivant arrête le préchargement :

export function destroyRewardedInterstitialAdPreloader(preloadId: string) {
  RewardedInterstitialAdPreloader.destroy(preloadId);
}

Une fois que l'utilisateur a fermé l'annonce ou si l'annonce ne s'affiche pas, détruisez les instances d'annonces interrogées individuellement. Pour en savoir plus, consultez Interroger et afficher l'annonce.

Voir l'exemple complet

Cette section décrit l'implémentation complète du préchargement des annonces.

L'exemple de composant suivant commence le préchargement lors de l'installation, suit le nombre d'annonces disponibles et fournit des commandes pour afficher les annonces interstitielles avec récompense préchargées :

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

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

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

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

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedInterstitialAd(
      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 Interstitial 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>
  );
}

Étapes suivantes

Après avoir intégré des annonces interstitielles avec récompense, explorez les sujets suivants :