Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

App-Start-Anzeigen einrichten

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 unter 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:

Richten Sie Google Mobile Ads SDK for React Native ein.
Aktivieren Sie Testanzeigen und verwenden Sie den folgenden Testanzeigenblock:

Android

ca-app-pub-3940256099942544/9257395921

iOS

ca-app-pub-3940256099942544/5575463023

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: Eine neue Anzeige wird 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 im Leitfaden Einzelne App-Start-Anzeige laden.

Vorabladen starten

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

export function startAppOpenAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = AppOpenAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`App open ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload app open ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('App open ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

Eine preloadId ist ein String, der eine Konfiguration für das Vorabladen von Anzeigen eindeutig identifiziert. Wenn die adUnitId nur für eine einzige Vorladekonfiguration in Ihrer App verwendet wird, 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 den Callback 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:

Standardlimit: Google speichert maximal sechs vorab geladene Anzeigen im Arbeitsspeicher.
Wir empfehlen, für jede Vorablade-ID eine Puffergröße von zwei beizubehalten.

Wenn Ihre App das appweite Limit erreicht, werden Hintergrundanfragen für vorab geladene Anzeigen pausiert, bis vorhandene Anzeigen abgerufen und angezeigt oder gelöscht werden.

Anzeige abrufen und einblenden

Mit der Methode AppOpenAdPreloader.pollAd können Sie prüfen, ob vorab geladene Anzeigen verfügbar sind, und eine Anzeigeninstanz abrufen.

Wenn Sie auf Ereignisse für die Vollbildpräsentation warten möchten, registrieren Sie Callbacks für das Attribut adEventCallback der zurückgegebenen AppOpenAd-Instanz, bevor Sie die Methode show aufrufen:

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

Wenn ein Nutzer eine Anzeige schließt oder die Anzeige nicht ausgeliefert werden kann, rufen Sie die Methode ad.destroy in den Callbacks onAdDismissedFullScreenContent und onAdFailedToShowFullScreenContent auf, um Arbeitsspeicher und Ressourcen freizugeben.

Informationen zur Antwort lesen

Wenn Sie Details der nächsten vorab geladenen Anzeige prüfen möchten, ohne die Anzeige aus dem Cache zu entfernen, rufen Sie die Methode AppOpenAdPreloader.peekAdResponseInfo auf:

export function peekAppOpenAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = AppOpenAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded app open ad response info:', responseInfo);
  }
  return responseInfo;
}

App-Start-Anzeigen mit einem Manager auf App-Ebene verwalten

Da App-Start-Anzeigen global beim Starten der App und beim Wechsel in den Vordergrund präsentiert werden, empfehlen wir, den Lebenszyklusstatus des Preloaders in einem Manager auf App-Ebene außerhalb des React-Komponentenbaums zu verwalten.

Die Verwendung eines Managers auf App-Ebene bietet mehrere wichtige Vorteile:

Der Preloader-Status bleibt unabhängig von der Navigation auf einzelnen Bildschirmen und dem Lebenszyklus von Komponenten.
Zentralisiert Anzeigenereignis-Callbacks, Status-Tracking und Bereinigung in einer einzigen freigegebenen Instanz in Ihrer App.
Steuert, wann auf Vordergrundereignisse gewartet wird, um doppelte Präsentationen beim Schließen der Anzeige zu verhindern.

Im folgenden Beispiel wird ein Manager auf Anwendungsebene mit dem AppOpenAdPreloader-Objekt implementiert:

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

Auf Ereignisse beim Wechsel der App in den Vordergrund warten

Wenn Sie Anzeigen einblenden möchten, wenn Ihre App wieder im Vordergrund ist, registrieren Sie einen change-Listener für das AppState-Modul in der Stammkomponente Ihrer App, z. B. App.tsx. Prüfen Sie, wann der Status zu active wechselt. Rufen Sie beispielsweise die Methode start für Ihre Ad Manager-Instanz in der Komponente App.tsx auf.

Wenn Anzeigen-Overlays oder Landingpages präsentiert werden, z. B. Vollbildanzeigen oder das Tippen auf eine Banneranzeige, wird Ihre Anwendung in den Hintergrund verschoben. Wenn der Nutzer zu Ihrer Anwendung zurückkehrt, empfängt Ihre Anwendung ein neues active-Statusereignis. So verhindern Sie eine unbeabsichtigte Anzeigenpräsentation oder eine Schleife, bei der nach der Rückkehr von einer Anzeige eine App-Start-Anzeige aus dem Cache präsentiert wird:

Entfernen Sie den Event-Listener AppState, bevor Sie eine Vollbildanzeige präsentieren.
Damit die Wiedergabe fortgesetzt wird, unabhängig davon, ob ein Nutzer die Anzeige schließt oder die Anzeige nicht eingeblendet wird, fügen Sie den Ereignis-Listener AppState noch einmal in den Callbacks onAdDismissedFullScreenContent und onAdFailedToShowFullScreenContent hinzu.

Ein vollständiges Beispiel dafür, wie Sie steuern, wann Ereignis-Listener im Vordergrund pausiert und fortgesetzt werden, finden Sie in der AppOpenAdManager-Implementierung.

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. App-Start-Anzeigen bei Kaltstarts nur auf einem Ladebildschirm einblenden, während 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.

Ressourcen bereinigen

Wenn das Vorabladen für einen Bildschirm oder eine Anzeigenblock-ID nicht mehr erforderlich ist, z. B. wenn Sie einen Bildschirm verlassen, auf dem Anzeigen vorab geladen werden, rufen Sie die Methode AppOpenAdPreloader.destroy auf, um die Ressourcen des Vorabladers freizugeben und zu verhindern, dass nicht verwendete Anzeigenobjekte im Arbeitsspeicher verbleiben:

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

Zusätzlich zum Löschen der Preloader-Warteschlange müssen Sie auch einzelne abgefragte Anzeigeninstanzen löschen, wenn ein Nutzer eine Anzeige schließt oder die Anzeige nicht ausgeliefert wird. Weitere Informationen finden Sie unter Anzeige abrufen und einblenden.

Vollständiges Beispiel ansehen

In der folgenden Beispielkomponente wird das Vorabladen beim Mounten gestartet, die Anzahl der verfügbaren Anzeigen wird erfasst und es werden Steuerelemente zum Einblenden vorab geladener App-Start-Anzeigen bereitgestellt:

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Ersetzen Sie Folgendes:

APP_OPEN_AD_UNIT_ID durch Ihre Anzeigenblock-ID.
PRELOAD_ID durch Ihre Preloader-ID.

Nächste Schritte

Nachdem Sie App-Start-Anzeigen eingebunden haben, können Sie sich mit den folgenden Themen befassen:

App-Start-Anzeigen einrichten Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.