Auf das Vorabladen von Anzeigen umstellen

Mit dem Vorabladen von Anzeigen werden das Laden, Caching und Neuladen von Anzeigen in GMA Next-Gen SDK automatisiert. Wenn Sie das einzelne Laden verwenden, sollten Sie zum Vorabladen von Anzeigen wechseln, um die automatische Lebenszyklusverwaltung, verwaltete Wiederholungen und eine optimierte Anzeigenauswahl zu nutzen. Konzeptionelle Details zum Vorabladen von Anzeigen finden Sie unter Vorabladen von Anzeigen. Das Vorabladen von Anzeigen unterstützt die Anzeigenformate App-Start-Anzeigen, Interstitial-Anzeigen, Anzeigen mit Prämie und Interstitial-Anzeigen mit Prämie.

Auf dieser Seite wird beschrieben, wie Sie eine vorhandene Implementierung für das einzelne Laden von Anzeigen zum Vorabladen von Anzeigen migrieren. In dieser Anleitung werden Interstitial-Anzeigen als Beispiel verwendet. Sie können jedoch denselben Prozess auf die unterstützten Anzeigenformate anwenden.

Vorbereitung

Führen Sie die folgenden Schritte aus, bevor Sie fortfahren:

Anzeigen mit Vorabladen von Anzeigen anfordern

Beim einzelnen Laden fordern Sie für jede Anzeigenanfrage eine einzelne Anzeige an. Beim Vorabladen von Anzeigen starten Sie das Vorabladen einmal mit Ihrer Vorabladen-ID und der Vorabladen-Konfiguration.

In den folgenden Beispielen werden Anzeigenanfragen mit einzelnem Laden und Vorabladen von Anzeigen verglichen:

Kotlin

Einzelnes Laden:

// Request a single ad.
val adRequest = AdRequest.Builder(adUnitId).build()
InterstitialAd.load(adRequest, adLoadCallback)

Vorabladen von Anzeigen:

// Start the preloader once with a preload configuration.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
InterstitialAdPreloader.start(adUnitId, preloadConfig)

Java

Einzelnes Laden:

// Request a single ad.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
InterstitialAd.load(adRequest, adLoadCallback);

Vorabladen von Anzeigen:

// Start the preloader once with a preload configuration.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
InterstitialAdPreloader.start(adUnitId, preloadConfig);

Zu Vorabladen-Callbacks wechseln

Beim einzelnen Laden fügen Sie jeder einzelnen Anzeigenanfrage einen Lade-Callback hinzu. Beim Vorabladen von Anzeigen registrieren Sie einen Callback-Listener, um Cache-Updates für das Vorabladen zu beobachten. Diese Callbacks benachrichtigen Ihre App, wenn das Vorabladen von Anzeigen abgeschlossen ist, das Laden fehlschlägt oder der Cache erschöpft ist.

In den folgenden Beispielen wird verglichen, wie Sie Vorabladen-Callbacks für das einzelne Laden und das Vorabladen von Anzeigen registrieren:

Kotlin

Einzelnes Laden:

// Listen for single ad request load results.
val adLoadCallback =
  object : AdLoadCallback<InterstitialAd> {
    override fun onAdLoaded(ad: InterstitialAd) {
      // Ad loaded for a single request.
    }

    override fun onAdFailedToLoad(adError: LoadAdError) {
      Log.d(TAG, "Ad failed to load: ${adError.message}")
    }
  }

InterstitialAd.load(adRequest, adLoadCallback)

Vorabladen von Anzeigen:

// Observe cache updates across multiple ads.
val preloadCallback =
  object : PreloadCallback {
    override fun onAdPreloaded(
      preloadId: String,
      responseInfo: ResponseInfo,
    ) {
      // Ad preloaded into the cache and is ready to show.
    }

    override fun onAdFailedToPreload(
      preloadId: String,
      adError: LoadAdError,
    ) {
      Log.d(TAG, "Ad failed to preload: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      // All preloaded ads in the cache have been shown.
      Log.d(TAG, "Ads exhausted for: $preloadId")
    }
  }

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

Java

Einzelnes Laden:

// Listen for single ad request load results.
AdLoadCallback<InterstitialAd> adLoadCallback =
    new AdLoadCallback<InterstitialAd>() {
      @Override
      public void onAdLoaded(@NonNull InterstitialAd ad) {
        // Ad loaded for a single request.
      }

      @Override
      public void onAdFailedToLoad(@NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to load: " + adError.getMessage());
      }
    };

InterstitialAd.load(adRequest, adLoadCallback);

Vorabladen von Anzeigen:

// Observe cache updates across multiple ads.
PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdPreloaded(
          @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        // Ad preloaded into the cache and is ready to show.
      }

      @Override
      public void onAdFailedToPreload(
          @NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        // All preloaded ads in the cache have been shown.
        Log.d(TAG, "Ads exhausted for: " + preloadId);
      }
    };

InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Das Vorabladen ruft Callback-Methoden auf, wenn GMA Next-Gen SDK eine Anzeige lädt oder im Cache speichert oder wenn Ihre App eine Anzeige präsentiert.

Anzeigen aus dem Cache präsentieren

Beim einzelnen Laden speichern Sie die geladene Anzeige in einer Variablen und präsentieren sie, wenn sie verfügbar ist. Beim Vorabladen von Anzeigen rufen Sie die Anzeige direkt aus dem Cache ab, wenn sie präsentiert werden kann. In beiden Fällen müssen Sie den Event-Listener an die Anzeige anhängen, bevor Sie sie präsentieren.

In den folgenden Beispielen wird verglichen, wie eine Anzeige mit Vorabladen von Anzeigen und mit einzelnem Laden präsentiert wird:

Kotlin

Einzelnes Laden:

// Retrieve the ad from a saved variable.
val interstitialAd = this.interstitialAd ?: return
// Display the ad.
interstitialAd.show(activity)

Vorabladen von Anzeigen:

// Retrieve the ad directly from the preloader cache.
val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
// Display the ad.
interstitialAd.show(activity)

Java

Einzelnes Laden:

// Retrieve the ad from a saved variable.
InterstitialAd interstitialAd = this.interstitialAd;
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

Vorabladen von Anzeigen:

// Retrieve the ad directly from the preloader cache.
InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
if (interstitialAd == null) {
  return;
}
// Display the ad.
interstitialAd.show(activity);

Manuelles Caching und Neuladen entfernen

Das Vorabladen lädt automatisch eine Ersatzanzeige, wenn Sie die Anzeige erhalten. Im Gegensatz zum einzelnen Laden müssen Sie keine Anzeigenreferenzen manuell speichern oder eine Neuladelogik schreiben.

Entfernen Sie die folgenden Muster aus Ihrem Code:

  • Caching von Membervariablen: Löschen Sie Membervariablen, in denen Anzeigenobjekte gespeichert sind.
  • Manuelles Neuladen: Löschen Sie Ladeaufrufe, nachdem der Nutzer die Anzeige geschlossen hat oder sie nicht präsentiert wurde.
  • Benutzerdefinierte Wiederholungstimer: Löschen Sie Wiederholungs-Handler, Backoff-Schleifen und Timer. GMA Next-Gen SDK wiederholt fehlgeschlagene Vorabladen-Anfragen automatisch.

Vollständige Beispiele vergleichen

In den folgenden Beispielen wird eine vollständige Implementierung von Interstitial-Anzeigen vor und nach der Migration zum Vorabladen von Anzeigen verglichen:

Kotlin

Einzelnes Laden:

// 1. Maintain a member variable to store the ad.
private var interstitialAd: InterstitialAd? = null

// 2. Load the ad and listen for load completion.
private fun loadAd() {
  val adRequest = AdRequest.Builder(adUnitId).build()
  InterstitialAd.load(
    adRequest,
    object : AdLoadCallback<InterstitialAd> {
      override fun onAdLoaded(ad: InterstitialAd) {
        interstitialAd = ad
      }

      override fun onAdFailedToLoad(adError: LoadAdError) {
        interstitialAd = null
      }
    },
  )
}

// 3. Show the saved ad.
private fun showAd(activity: Activity) {
  val interstitialAd = this.interstitialAd ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Reload the ad after dismissal in single-load integrations.
        loadAd()
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

Vorabladen von Anzeigen:

// 1. Start preloading with a callback to listen for loaded ads.
private fun startPreloading(adUnitId: String) {
  val preloadCallback =
    object : PreloadCallback {
      override fun onAdPreloaded(
        preloadId: String,
        responseInfo: ResponseInfo,
      ) {
        // Ad preloaded successfully.
      }

      override fun onAdFailedToPreload(
        preloadId: String,
        adError: LoadAdError,
      ) {
        Log.d(TAG, "Ad failed to preload: ${adError.message}")
      }
    }

  val adRequest = AdRequest.Builder(adUnitId).build()
  val preloadConfig = PreloadConfiguration(adRequest)
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)
}

// 2. Show the ad immediately after polling.
private fun showAd(activity: Activity, adUnitId: String) {
  val interstitialAd = InterstitialAdPreloader.pollAd(adUnitId) ?: return
  interstitialAd.adEventCallback =
    object : InterstitialAdEventCallback {
      override fun onAdDismissedFullScreenContent() {
        // Preloading automatically fetches a replacement ad.
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError,
      ) {
        Log.d(TAG, "Ad failed to show: ${fullScreenContentError.message}")
      }
    }
  interstitialAd.show(activity)
}

Java

Einzelnes Laden:

// 1. Maintain a member variable to store the ad.
private InterstitialAd interstitialAd;

// 2. Load the ad and listen for load completion.
private void loadAd() {
  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  InterstitialAd.load(
      adRequest,
      new AdLoadCallback<InterstitialAd>() {
        @Override
        public void onAdLoaded(@NonNull InterstitialAd ad) {
          interstitialAd = ad;
        }

        @Override
        public void onAdFailedToLoad(@NonNull LoadAdError adError) {
          interstitialAd = null;
        }
      });
}

// 3. Show the saved ad.
private void showAd(Activity activity) {
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Reload the ad after dismissal in single-load integrations.
          loadAd();
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

Vorabladen von Anzeigen:

// 1. Start preloading with a callback to listen for loaded ads.
private void startPreloading(String adUnitId) {
  PreloadCallback preloadCallback =
      new PreloadCallback() {
        @Override
        public void onAdPreloaded(
            @NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
          // Ad preloaded successfully.
        }

        @Override
        public void onAdFailedToPreload(
            @NonNull String preloadId, @NonNull LoadAdError adError) {
          Log.d(TAG, "Ad failed to preload: " + adError.getMessage());
        }
      };

  AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
  PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
  InterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);
}

// 2. Show the ad immediately after polling.
private void showAd(Activity activity, String adUnitId) {
  InterstitialAd interstitialAd = InterstitialAdPreloader.pollAd(adUnitId);
  if (interstitialAd == null) {
    return;
  }
  interstitialAd.setAdEventCallback(
      new InterstitialAdEventCallback() {
        @Override
        public void onAdDismissedFullScreenContent() {
          // Preloading automatically fetches a replacement ad.
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          Log.d(
              TAG,
              "Ad failed to show: " + fullScreenContentError.getMessage());
        }
      });
  interstitialAd.show(activity);
}

Nächste Schritte

In den folgenden Ressourcen erfahren Sie, wie Sie Vorabladen-Funktionen konfigurieren, Anzeigenformate einbinden und Ihre Implementierung testen: