Einzelne App-Start-Anzeige laden

App-Start-Anzeigen werden eingeblendet, wenn Nutzer Ihre App öffnen oder zu ihr zurückkehren. Nutzer können App-Start-Anzeigen jederzeit schließen. Wenn Sie den Ladebildschirm Ihrer App monetarisieren möchten, verwenden Sie App-Start-Anzeigen. Weitere Informationen finden Sie hier:

Leitfaden und Best Practices für App-Start-Anzeigen

In diesem Leitfaden wird beschrieben, wie Sie App-Start-Anzeigen in eine React Native-App einbinden.

Vorbereitung

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

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

Anzeige laden

Rufen Sie die Methode load auf, um eine App-Start-Anzeige zu laden.

Im folgenden Beispiel wird eine App-Start-Anzeige geladen, wenn der Vorgang erfolgreich ist. Wenn ein Fehler auftritt, wird er protokolliert:

export async function loadAppOpenAd(
  adUnitId: string,
): Promise<AppOpenAd | null> {
  try {
    const ad = await AppOpenAd.load({adUnitId});
    return ad;
  } catch (error) {
    const loadError = error as LoadAdError;
    console.error('Failed to load app open ad:', loadError.message);
    return null;
  }
}

Auf Anzeigenereignisse warten

Bevor Sie die Anzeige präsentieren, legen Sie den adEventCallback-Listener für die geladene AppOpenAd-Instanz fest. Dieser Listener empfängt Callbacks von Lifecycle-Events der Anzeige, z. B. wenn die Anzeige auf dem Bildschirm erscheint oder ein Nutzer darauf tippt. Informationen zu verfügbaren Callbacks finden Sie unter AdEventCallback.

Im folgenden Beispiel werden Callbacks festgelegt, um auf Anzeigenereignisse zu warten:

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

In diesem Beispiel wird auch die Methode destroy verwendet, wenn ein Nutzer die Anzeige schließt oder die Anzeige nicht ausgeliefert werden kann. Dadurch werden die von der Anzeige verwendeten Ressourcen freigegeben.

Anzeige einblenden

Rufen Sie die Methode show auf, um eine App-Start-Anzeige einzublenden:

export function showAppOpenAd(ad: AppOpenAd) {
  ad.show();
}

Anzeigen mit einem Manager auf App-Ebene verwalten

Wir empfehlen, App-Start-Anzeigen in einem Manager auf App-Ebene außerhalb des React-Komponentenbaums zu verwalten. Da App-Start-Anzeigen global ausgeliefert werden, wenn ein Nutzer Ihre App öffnet oder zu ihr zurückkehrt, werden die Anzeigen durch einen Manager auf App-Ebene von der Benutzeroberfläche getrennt.

Im folgenden Beispiel wird eine SingleLoadAppOpenAdManager-Instanz erstellt, die eine Anzeige lädt, auf Anzeigenereignisse wartet und die Anzeigenverfügbarkeit prüft:

export class SingleLoadAppOpenAdManager {
  private ad: AppOpenAd | null = null;
  private loadTime = 0;
  private isShowingAd = false;

  async loadAd(adUnitId: string) {
    // Avoid re-loading if an ad is already loaded or showing.
    if (this.ad) {
      return;
    }
    try {
      this.ad = await AppOpenAd.load({adUnitId});
      this.loadTime = Date.now();
      this.ad.adEventCallback = {
        onAdDismissedFullScreenContent: () => {
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          // Preload the next ad for future foreground transitions.
          this.loadAd(adUnitId);
        },
        onAdFailedToShowFullScreenContent: () => {
          // An ad object that fails to present is consumed and cannot be reused.
          // Clean up native resources and preload a new ad for future events.
          this.ad?.destroy();
          this.ad = null;
          this.isShowingAd = false;
          this.loadAd(adUnitId);
        },
      };
    } catch (error) {
      console.error('Failed to load app open ad:', error);
    }
  }

  showAdIfAvailable() {
    if (!this.ad || !this.isAdAvailable()) {
      console.warn(
        'App open ad cannot be shown: ad is not loaded or has expired.',
      );
      return;
    }
    if (this.isShowingAd) {
      console.warn('App open ad cannot be shown: an ad is already displaying.');
      return;
    }

    this.ad.show();
    this.isShowingAd = true;
  }

  isAdAvailable(): boolean {
    // App Open ads expire after 4 hours per Google Mobile Ads policy.
    const FOUR_HOURS_IN_MS = 4 * 60 * 60 * 1000;
    return this.ad !== null && Date.now() - this.loadTime < FOUR_HOURS_IN_MS;
  }
}

Ein Manager auf App-Ebene bietet Ihnen folgende Möglichkeiten:

  • Der Anzeigenstatus sollte unabhängig von der Bildschirmnavigation und dem Lebenszyklus der Komponenten sein.
  • Präsentationsstatus der Anzeige über native Thread-Ereignisse hinweg verfolgen.
  • Wechsel in den Vordergrund verarbeiten, um zu vermeiden, dass Anzeigen wiederholt ausgeliefert werden
  • Laden Sie Anzeigen im Hintergrund vor, damit sie beim Öffnen der App verfügbar sind.
  • Achten Sie darauf, dass Anzeigen nicht länger als vier Stunden gültig sind, um die Auslieferung abgelaufener Anzeigen zu vermeiden.
  • Laden, Einblenden und Bereinigen von Anzeigenressourcen kombinieren

Auf App-Vordergrundereignisse warten

Wenn Sie Anzeigen einblenden möchten, wenn Ihre App wieder in den Vordergrund wechselt, verwenden Sie das Modul AppState, um auf Änderungen des App-Status im Stammverzeichnis Ihrer App zu warten, z. B. in der Datei App.tsx. Gehen Sie dazu so vor:

  1. Registrieren Sie einen AppState-Listener für das 'change'-Ereignis.
  2. Wenn der Status in 'active' wechselt, rufen Sie die Methode showAdIfAvailable für die AdManager-Instanz auf.

Im folgenden Beispiel wird auf Ereignisse im Vordergrund der App gewartet und eine Anzeige eingeblendet, falls verfügbar:

export function setupAppOpenAdForegroundListener(adManager: {
  showAdIfAvailable: () => void;
}): NativeEventSubscription {
  return AppState.addEventListener('change', (nextAppState: AppStateStatus) => {
    if (nextAppState === 'active') {
      adManager.showAdIfAvailable();
    }
  });
}

Kaltstarts und Ladebildschirme kennenlernen

Ein Kaltstart tritt auf, wenn Ihre App von Grund auf neu gestartet wird, z. B. wenn ein Nutzer Ihre App zum ersten Mal öffnet oder nachdem das Gerät die App geschlossen hat, um Speicherplatz freizugeben. Bei einem Kaltstart ist keine zuvor geladene App-Start-Anzeige vorhanden, die als Nächstes eingeblendet werden kann.

Aufgrund von Verzögerungen bei Anzeigenanfragen interagieren Nutzer möglicherweise mit Ihrer App, bevor eine Anzeige erscheint. Um die Nutzerfreundlichkeit nicht zu beeinträchtigen, sollten Sie App-Start-Anzeigen bei Kaltstarts nur auf einem Ladebildschirm einblenden, während die App-Assets geladen werden. Wenn die Assets geladen wurden und der Nutzer den Hauptinhalt erreicht, bevor die Anzeige geladen wurde, sollte die Anzeige nicht mehr präsentiert werden.

Testbildschirm einrichten

Wenn Sie Anzeigen interaktiv testen oder auf einem bestimmten Bildschirm anzeigen möchten, verwalten Sie die Anzeigeninstanz im Komponentenstatus.

Im folgenden Beispiel wird eine App-Start-Anzeige mit einem useEffect-Bereinigungs-Hook in eine React Native-Komponente eingebunden. Wenn die Komponente vor der Auslieferung der Anzeige entfernt wird, werden durch diesen Hook native Ressourcen freigegeben.

export function AppOpenSingleLoadScreen() {
  const [ad, setAd] = useState<AppOpenAd | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [status, setStatus] = useState<string>('Idle');

  useEffect(() => {
    return () => {
      ad?.destroy();
    };
  }, [ad]);

  const handleLoad = async () => {
    setStatus('Loading App Open ad...');
    const loadedAd = await loadAppOpenAd(APP_OPEN_AD_UNIT_ID);
    if (loadedAd) {
      registerAdEvents(loadedAd);
      const onDismiss =
        loadedAd.adEventCallback?.onAdDismissedFullScreenContent;
      loadedAd.adEventCallback = {
        ...loadedAd.adEventCallback,
        onAdDismissedFullScreenContent: () => {
          onDismiss?.();
          setStatus('Ad dismissed.');
        },
      };
      setAd((prevAd) => {
        prevAd?.destroy();
        return loadedAd;
      });
      setIsLoaded(true);
      setStatus('App Open ad loaded!');
    } else {
      setStatus('Failed to load App Open ad.');
    }
  };

  const handleShow = () => {
    if (ad) {
      showAppOpenAd(ad);
      setIsLoaded(false);
    }
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>App Open Ad</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <View style={styles.buttonGroup}>
        <Button title="Load Ad" onPress={handleLoad} />
        <View style={styles.spacerSmall} />
        <Button title="Show Ad" onPress={handleShow} disabled={!isLoaded} />
      </View>
    </View>
  );
}

Nächste Schritte

Nachdem Sie eine App-Start-Anzeige eingebunden haben, sollten Sie sich mit den folgenden Themen vertraut machen: