Configurer des annonces avec récompense

Les annonces avec récompense offrent aux utilisateurs des éléments intégrés lorsqu'ils interagissent avec des annonces vidéo, des annonces jouables et des enquêtes. Pour en savoir plus, consultez Présentation des blocs d'annonces avec récompense.

Pour éliminer la latence de présentation et s'assurer qu'une annonce est disponible lorsqu'un utilisateur gagne une récompense, 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 annonces avec récompense dans une application React Native.

Prérequis

Avant de continuer, procédez comme suit :

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

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 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 avec récompense.

Démarrer le préchargement

Pour commencer à précharger des annonces, appelez la méthode RewardedAdPreloader.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 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 préchargement est une chaîne qui identifie de manière unique une configuration de préchargement d'annonces. Si vous utilisez l'ID du bloc d'annonces pour une seule configuration de préchargement dans votre application, vous pouvez utiliser cet ID 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 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 pour l'ensemble des blocs d'annonces et des ID de préchargement :

  • 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.
  • Taille de la mémoire tampon recommandée : deux 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 de diffuser une annonce, vérifiez qu'elle est disponible en appelant la méthode RewardedAdPreloader.isAdAvailable. Pour récupérer l'annonce, appelez la méthode RewardedAdPreloader.pollAd.

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 avant de diffuser l'annonce :

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

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 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 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 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 avec récompense avant d'afficher une annonce :

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  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 RewardedAdPreloader.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 destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.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

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 avec récompense préchargées :

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

Remplacez les éléments suivants :

  • REWARDED_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 avec récompense, explorez les thèmes suivants :