Aller au contenu
rdlabo.devdocs

Annonces récompensées

Les annonces récompensées permettent d’attribuer des éléments dans l’application en échange d’interactions avec des vidéos publicitaires, des annonces jouables ou des sondages. Les guides Google sur les annonces récompensées pour Android et iOS expliquent ce format.

Traitez les annonces récompensées comme un parcours de récompense, pas comme une autre interstitielle sans récompense. Appelez cette méthode après l’initialisation et le consentement. Attribuez la récompense uniquement à partir du résultat renvoyé ou de l’événement Rewarded, pas de Dismissed.

Vidéo récompensée

Utilisez une annonce récompensée pour un parcours dédié à la récompense.

import {
  AdLoadInfo,
  AdMob,
  AdMobRevenueData,
  AdMobRewardItem,
  RewardAdOptions,
  RewardAdPluginEvents,
} from '@capacitor-community/admob';

await AdMob.addListener(RewardAdPluginEvents.Loaded, (info: AdLoadInfo) => {
  console.log('Rewarded ad loaded', info.adUnitId);
});
await AdMob.addListener(RewardAdPluginEvents.FailedToLoad, console.error);
await AdMob.addListener(RewardAdPluginEvents.Rewarded, (reward: AdMobRewardItem) => {
  console.log('Reward earned', reward.amount, reward.type);
});
await AdMob.addListener(RewardAdPluginEvents.AdImpression, (data: AdMobRevenueData) => {
  console.log(data);
});

const options: RewardAdOptions = {
  adId: 'YOUR_AD_UNIT_ID',
  // isTesting: true,
  // npa: true,
  // immersiveMode: true,
  // ssv: {
  //   userId: 'USER_ID',
  //   customData: JSON.stringify({ placement: 'bonus' }),
  // },
};
await AdMob.prepareRewardVideoAd(options);
const rewardItem = await AdMob.showRewardVideoAd();
// Attribuez la récompense une seule fois, avec ce résultat ou l’événement Rewarded — pas les deux.
console.log(rewardItem);

method prepareRewardVideoAd(...)

Charge une annonce récompensée et renvoie l’identifiant du bloc d’annonces chargé.

prepareRewardVideoAd(options: RewardAdOptions) => Promise<AdLoadInfo>

method showRewardVideoAd(...)

Affiche une annonce récompensée chargée et se résout lorsque l’utilisateur obtient la récompense.

showRewardVideoAd(options?: AdShowOptions | undefined) => Promise<AdMobRewardItem>

interface RewardAdOptions

Options de chargement d’une annonce récompensée.

Propriété Type Description Valeur par défaut Depuis
ssv AtLeastOne<{ /** * A user identifier passed to the SSV callback. */ userId: string; /** * Custom data passed to the SSV callback. */ customData: string; }> Options de vérification côté serveur pour l’annonce récompensée. Fournissez au moins l’un des paramètres userId ou customData.
adId string Identifiant du bloc d’annonces à charger. 1.1.2
isTesting boolean Indique si une annonce de test doit être demandée. false 1.1.2
margin number Marge de la bannière en unités logiques d’affichage : dp sur Android et points sur iOS. Pour BOTTOM_CENTER, il s’agit de la marge inférieure. Pour TOP_CENTER, il s’agit de la marge supérieure. 0 1.1.2
npa boolean Indique si des annonces non personnalisées doivent être demandées. false 1.2.0
immersiveMode boolean Indique si une annonce plein écran doit être affichée en mode immersif sur Android. 7.0.3

interface AdMobRewardItem

Récompense obtenue par l’utilisateur après avoir regardé une annonce récompensée.

Propriété Type Description
type string Type de récompense configuré pour le bloc d’annonces.
amount number Montant de la récompense obtenue par l’utilisateur.

Sans adId passé à showRewardVideoAd(), l’annonce préparée le plus récemment est affichée.

Préparer plusieurs annonces

await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });
await AdMob.prepareRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-2' });

const reward = await AdMob.showRewardVideoAd({ adId: 'ca-app-pub-xxx/reward-1' });

Interstitielle récompensée

Les annonces interstitielles récompensées sont des annonces plein écran incitatives qui apparaissent lors de transitions naturelles dans l’application. Contrairement à la vidéo récompensée, l’utilisateur ne choisit pas d’y participer au préalable. Les guides Google sur les interstitielles récompensées pour Android et iOS expliquent ce format.

Utilisez une interstitielle récompensée lorsque l’expérience récompensée doit intervenir à une transition naturelle dans l’application.

import {
  AdMob,
  AdMobRewardInterstitialItem,
  RewardInterstitialAdOptions,
  RewardInterstitialAdPluginEvents,
} from '@capacitor-community/admob';

await AdMob.addListener(RewardInterstitialAdPluginEvents.FailedToLoad, console.error);

const options: RewardInterstitialAdOptions = {
  adId: 'YOUR_AD_UNIT_ID',
};
const { adUnitId } = await AdMob.prepareRewardInterstitialAd(options);
const rewardItem: AdMobRewardInterstitialItem = await AdMob.showRewardInterstitialAd({
  adId: adUnitId,
});
console.log(rewardItem);

method prepareRewardInterstitialAd(...)

Charge une annonce interstitielle récompensée et renvoie l’identifiant du bloc d’annonces chargé.

prepareRewardInterstitialAd(options: RewardInterstitialAdOptions) => Promise<AdLoadInfo>

method showRewardInterstitialAd(...)

Affiche une annonce interstitielle récompensée chargée et se résout lorsque l’utilisateur obtient la récompense.

showRewardInterstitialAd(options?: AdShowOptions | undefined) => Promise<AdMobRewardInterstitialItem>

interface RewardInterstitialAdOptions

Options de chargement d’une annonce interstitielle récompensée.

Propriété Type Description Valeur par défaut Depuis
ssv AtLeastOne<{ /** * A user identifier passed to the SSV callback. */ userId: string; /** * Custom data passed to the SSV callback. */ customData: string; }> Options de vérification côté serveur pour l’annonce interstitielle récompensée. Fournissez au moins l’un des paramètres userId ou customData.
adId string Identifiant du bloc d’annonces à charger. 1.1.2
isTesting boolean Indique si une annonce de test doit être demandée. false 1.1.2
margin number Marge de la bannière en unités logiques d’affichage : dp sur Android et points sur iOS. Pour BOTTOM_CENTER, il s’agit de la marge inférieure. Pour TOP_CENTER, il s’agit de la marge supérieure. 0 1.1.2
npa boolean Indique si des annonces non personnalisées doivent être demandées. false 1.2.0
immersiveMode boolean Indique si une annonce plein écran doit être affichée en mode immersif sur Android. 7.0.3

interface AdMobRewardInterstitialItem

Récompense obtenue par l’utilisateur après avoir regardé une annonce interstitielle récompensée.

Propriété Type Description
type string Type de récompense configuré pour le bloc d’annonces.
amount number Montant de la récompense obtenue par l’utilisateur.

Consultez Tests pour isTesting.

Vérification côté serveur

La vérification côté serveur (SSV) permet à votre backend de confirmer qu’une récompense a été obtenue. Consultez la documentation SSV de Google. Les callbacks sont déclenchés uniquement pour les annonces de production ; les annonces de test n’appellent pas votre endpoint SSV.

Pour valider localement la charge utile ssv, vous pouvez envoyer une demande simulée après RewardAdPluginEvents.Rewarded. Remplacez ENVIRONMENT_IS_DEVELOPMENT par votre propre indicateur de développement :

const userId = 'USER_ID';
const customData = JSON.stringify({ placement: 'bonus' });

await AdMob.addListener(RewardAdPluginEvents.Rewarded, async () => {
  if (!ENVIRONMENT_IS_DEVELOPMENT) {
    return;
  }
  try {
    const params = new URLSearchParams({
      ad_network: 'TEST',
      ad_unit: 'TEST',
      custom_data: customData,
      reward_amount: 'TEST',
      reward_item: 'TEST',
      timestamp: 'TEST',
      transaction_id: 'TEST',
      user_id: userId,
      signature: 'TEST',
      key_id: 'TEST',
    });
    await fetch(`https://your-staging-ssv-endpoint?${params.toString()}`);
  } catch (err) {
    console.error(err);
  }
});
Modifier cette page sur GitHub