Anzeigen mit Prämie einrichten

Bei Anzeigen mit Prämie erhalten Nutzer In-App-Artikel, wenn sie mit Videoanzeigen, spielbaren Anzeigen und Umfragen interagieren. Weitere Informationen finden Sie unter Anzeigenblöcke für Anzeigen mit Prämie.

Um die Präsentationslatenz zu eliminieren und sicherzustellen, dass eine Anzeige verfügbar ist, wenn ein Nutzer eine Prämie erhält, wird bei Google Mobile Ads SDK for React Native das Vorabladen von Anzeigen verwendet, um das Laden im Hintergrund, das Caching und das Auffüllen des Puffers zu verwalten.

In diesem Leitfaden erfahren Sie, wie Sie Anzeigen mit Prämie in eine React Native-App einbinden.

Vorbereitung

Bevor Sie fortfahren, führen Sie die folgenden Schritte aus:

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

Vorabladen von Anzeigen

Das Vorabladen von Anzeigen in Google Mobile Ads SDK for React Native automatisiert das Laden und Caching von Anzeigen.

Das Vorabladen von Anzeigen bietet folgende Vorteile:

  • Referenzverwaltung: Referenzen werden beibehalten, bis Anzeigen ausgeliefert werden.
  • Automatisches Aktualisieren: Es wird eine neue Anzeige geladen, wenn eine Anzeige aus dem Cache abgerufen wird.
  • Verwaltete Wiederholungsversuche: Es wird eine neue Anzeige geladen, wenn das Laden einer Anzeige fehlschlägt.
  • Ablaufbehandlung: Anzeigen werden vor dem Ablauf aktualisiert.
  • Cache-Optimierung: Die Cache-Reihenfolge wird optimiert, damit die Anzeige mit der höchsten Priorität ausgeliefert wird.

Informationen zum manuellen Laden von Anzeigen finden Sie unter Einzelne Anzeige mit Prämie laden.

Vorabladen starten

Wenn Sie mit dem Vorabladen von Anzeigen beginnen möchten, rufen Sie die Methode RewardedAdPreloader.start auf und übergeben Sie den Wert preloadId, die Konfigurationseinstellungen und die Ereignis-Callbacks, um Änderungen am Pufferstatus zu überwachen:

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

Eine Vorablade-ID ist ein String, der eine Konfiguration für das Vorabladen von Anzeigen eindeutig identifiziert. Wenn Sie die Anzeigenblock-ID für eine einzelne Vorladekonfiguration in Ihrer App verwenden, können Sie diese Anzeigenblock-ID als Vorlade-ID verwenden. Wenn für Ihre App mehrere Preloader für dieselbe Anzeigenblock-ID erforderlich sind, übergeben Sie für jede Preload-ID einen eindeutigen String.

Wenn Ihre App eine vorab geladene Anzeige aus dem Zwischenspeicher abruft, fordert Google Mobile Ads SDK for React Native im Hintergrund eine Ersatzanzeige an, um den Zwischenspeicher wieder aufzufüllen. Wenn keine vorab geladenen Anzeigen mehr im Zwischenspeicher vorhanden sind, ruft Google Mobile Ads SDK for React Native die onAdsExhausted auf.

Limits für den Vorab-Cache

Google Mobile Ads SDK for React Native erzwingt ein appweites Limit für die Gesamtzahl der vorab geladenen Anzeigen für alle Anzeigenblöcke und Preload-IDs:

  • Standardlimit: Google speichert maximal sechs vorab geladene Anzeigen im Arbeitsspeicher. Dieses Limit gilt für alle Formate und Vorablade-IDs.
  • Empfohlene Puffergröße: zwei für jede Preload-ID.

Wenn Ihre App das appweite Limit erreicht, werden Hintergrundanfragen für vorab geladene Anzeigen pausiert, bis vorhandene Anzeigen aus dem Cache abgerufen oder gelöscht werden. Das Vorabladen wird auch vorübergehend pausiert, während eine Vollbildanzeige auf dem Bildschirm zu sehen ist.

Anzeige abrufen und einblenden

Bevor Sie eine Anzeige einblenden, prüfen Sie mit der Methode RewardedAdPreloader.isAdAvailable, ob eine Anzeige verfügbar ist. Rufen Sie die Methode RewardedAdPreloader.pollAd auf, um die Anzeige abzurufen.

Wenn Sie auf Präsentationsereignisse wie das Schließen von Anzeigen oder Anzeigefehler warten möchten, legen Sie die Property adEventCallback für die Anzeigeninstanz fest, bevor Sie die Methode show aufrufen:

Im folgenden Beispiel wird die Verfügbarkeit von Anzeigen geprüft und auf Präsentationsereignisse gewartet, bevor die Anzeige ausgeliefert wird:

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

Rufen Sie die Methode ad.destroy in den Callbacks onAdDismissedFullScreenContent und onAdFailedToShowFullScreenContent auf, um Arbeitsspeicher und Ressourcen freizugeben.

Informationen zur Antwort lesen

Wenn Sie die Antwortinformationen für die nächste vorab geladene Anzeige prüfen möchten, ohne die Anzeige aus dem Cache zu entfernen, rufen Sie die Methode RewardedAdPreloader.peekAdResponseInfo auf:

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

Wenn eine Anzeige verfügbar ist, gibt die Methode peekAdResponseInfo ein ResponseInfo-Objekt mit Informationen zur geladenen Anzeigenquelle und zu den Netzwerkadaptern zurück.

Optional: Serverseitige Überprüfungs-Callbacks validieren

Wenn für Ihre App benutzerdefinierte Überprüfungsparameter wie eine Nutzer-ID oder benutzerdefinierte Prämienmetadaten in serverseitigen Überprüfungs-Callbacks (SSV) erforderlich sind, legen Sie die Property serverSideVerificationOptions für die abgefragte Anzeigeninstanz fest, bevor Sie show aufrufen.

Die von Ihnen festgelegten Werte werden an die SSV-Callback-Suchparameter übergeben:

  • userId: Wird an den Suchparameter user_id übergeben, um den Nutzer zu identifizieren.
  • customData: Wird an den Suchparameter custom_data übergeben, um benutzerdefinierte Metadaten weiterzuleiten.

Im folgenden Beispiel wird ServerSideVerificationOptions (customData und userId) für ein Anzeigenobjekt mit Prämie festgelegt, bevor eine Anzeige eingeblendet wird:

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

Ressourcen bereinigen

Wenn Sie für den Rest der Sitzung keine Anzeigen mehr für eine bestimmte Vorablade-ID ausliefern müssen, rufen Sie die Methode RewardedAdPreloader.destroy auf. Dadurch wird das Vorabladen für diese Vorablade-ID beendet und nicht verwendete vorab geladene Anzeigen werden aus dem Speicher entfernt.

Im folgenden Beispiel wird das Vorabladen beendet:

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

Nachdem der Nutzer die Anzeige geschlossen hat oder wenn die Anzeige nicht ausgeliefert werden kann, müssen Sie die einzelnen abgerufenen Anzeigeninstanzen löschen. Weitere Informationen finden Sie unter Anzeige abrufen und einblenden.

Vollständiges Beispiel ansehen

Die folgende Beispielkomponente startet das Vorabladen beim Mounten, verfolgt die Anzahl der verfügbaren Anzeigen und bietet Steuerelemente zum Anzeigen von vorab geladenen Anzeigen mit Prämie:

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

Ersetzen Sie Folgendes:

  • REWARDED_AD_UNIT_ID durch Ihre Anzeigenblock-ID.
  • PRELOAD_ID durch Ihre Preloader-ID.

Nächste Schritte

Nachdem Sie Anzeigen mit Prämie eingebunden haben, können Sie sich mit den folgenden Themen beschäftigen: