Ödüllü geçiş reklamları oluşturma

Yeni Nesil SDK

Ödüllü geçiş reklamları, doğal uygulama geçişleri sırasında otomatik olarak görünen reklamlar için ödül sunmanıza olanak tanıyan bir biçimdir. Ödüllü reklamların aksine kullanıcıların ödüllü geçiş reklamı görüntülemeyi etkinleştirmesi gerekmez. Daha fazla bilgi için Ödüllü geçiş reklamı kılavuzu'na bakın.

Bu kılavuzda, ödüllü geçiş reklamlarının Android uygulamalarına nasıl entegre edileceği açıklanmaktadır.

Başlamadan önce

Devam etmeden önce aşağıdakileri yapın:

• GMA Next-Gen SDK kurulumunu yapın.
• Test ödüllü geçiş reklamı birimi kimliğini ca-app-pub-3940256099942544/5354046379 kullanın.
  • Uygulamanızı oluşturup test ederken etkin ve oluşturulma aşamasındaki reklamlar yerine test reklamlarını kullandığınızdan emin olun. Bu işlemi yapmazsanız hesabınız askıya alınabilir.
  • Uygulamanızı yayınlamadan önce bu kimliği reklam birimi kimliğinizle değiştirin.
  • GMA Next-Gen SDK test reklamları hakkında ayrıntılı bilgi için Test reklamlarını etkinleştirme başlıklı makaleyi inceleyin.

Reklam ön yüklemesini anlama

GMA Next-Gen SDK içinde reklam önceden yükleme, reklam yükleme ve önbelleğe alma işlemlerini otomatikleştirir.

Reklam önceden yükleme aşağıdaki avantajları sağlar:

• Referans yönetimi: Reklamlar gösterilene kadar referansları korur.
• Otomatik yeniden yükleme: Önbellekten bir reklam alındığında yeni bir reklam yükler.
• Yönetilen yeniden denemeler: Bir reklam yüklenemediğinde yeni bir reklam yükler.
• Geçerlilik süresi yönetimi: Reklamları geçerlilik süreleri dolmadan önce yeniler.
• Önbellek optimizasyonu: En yüksek öncelikli reklamı yayınlamak için önbellek sırasını optimize eder.

Reklam ön yüklemesini başlatma

Reklamları önceden yüklemeye başlamak için startPreload() yöntemini uygulama başlangıcında bir kez çağırın. startPreload() yöntemini çağırdıktan sonra, GMA Next-Gen SDK reklamlar otomatik olarak önceden yüklenir ve önceden yüklenmiş yapılandırmalar için başarısız olan istekler yeniden denenir.

Aşağıdaki örnekte, reklamların önceden yüklenmeye nasıl başlanacağı gösterilmektedir:

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

// Call start() once after SDK initialization.
// Preload only one ad unit per format to optimize performance.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

AD_UNIT_ID yerine reklam birimi kimliğinizi yazın.

Önceki örnekte, reklam birimi kimliğinin önceden yükleme kimliği olarak nasıl kullanılacağı gösterilmektedir. Önceden yükleme kimliği, reklam önceden yükleme yapılandırmasını tanımlamak için oluşturduğunuz dize tanımlayıcıdır. Uygulamanız aynı reklam birimi kimliği için birden fazla hedefleme yapılandırması gerektiriyorsa özel bir dize tanımlayıcı iletin.

Önceden yüklenmiş reklamı alma ve gösterme

Reklam göstermek istediğinizde pollAd() yöntemini çağırın. GMA Next-Gen SDK, kullanılabilir bir reklamı alır ve arka planda bir sonraki reklamı otomatik olarak önceden yükler. Reklam yoksa GMA Next-Gen SDK reklam döndürmez.

Kullanılabilir bir reklam nesneniz olduğunda reklamı göstermek için show yöntemini çağırın. Ödül etkinliklerini işlemek için ödül işleyici kullanın. Aşağıdaki örnekte, önceden yüklenmiş bir reklamın nasıl alınacağı ve gösterileceği açıklanmaktadır:

private fun pollAndShowAd(activity: Activity, adUnitId: String) {
  // Polling returns the next available ad and loads another ad in the background.
  val ad = RewardedInterstitialAdPreloader.pollAd(adUnitId)
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.")
    return
  }

  // Interact with the ad object as needed.
  Log.d(TAG, "Rewarded interstitial ad response info: ${ad.getResponseInfo()}")
  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdImpression() {
        Log.d(TAG, "Rewarded interstitial ad recorded an impression.")
      }
    }
  ad.show(activity) { rewardItem -> Log.d(TAG, "User earned reward: ${rewardItem.amount}") }
}

private void pollAndShowAd(Activity activity, String adUnitId) {
  // Polling returns the next available ad and loads another ad in the background.
  final RewardedInterstitialAd ad = RewardedInterstitialAdPreloader.pollAd(adUnitId);

  // Interact with the ad object as needed.
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not available.");
    return;
  }

  Log.d(TAG, "Rewarded interstitial ad response info: " + ad.getResponseInfo());
  ad.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdImpression() {
          Log.d(TAG, "Rewarded interstitial ad recorded an impression.");
        }
      });

  // Show the ad.
  ad.show(
      activity,
      rewardItem -> {
        Log.d(TAG, "User earned reward: " + rewardItem.getAmount());
      });
}

Reklam göstermeye hazır olana kadar pollAd() yöntemini çağırmaktan kaçının. Reklam yanıtı bilgilerini göstermeden okumak için Yanıt bilgilerini okuma başlıklı makaleyi inceleyin.

Reklam etkinliklerini dinleme

Reklamı göstermeden önce reklam etkinliklerini dinleyin. Aşağıdaki örnekte, reklam etkinlikleri için geri çağırma işlevlerinin nasıl kaydedileceği gösterilmektedir:

private fun listenToAdEvents() {
  // Listen for ad events.
  val ad = rewardedInterstitialAd
  if (ad == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.")
    return
  }

  ad.adEventCallback =
    object : RewardedInterstitialAdEventCallback {
      override fun onAdShowedFullScreenContent() {
        // Rewarded interstitial ad did show.
      }

      override fun onAdDismissedFullScreenContent() {
        // Rewarded interstitial ad did dismiss.
        rewardedInterstitialAd = null
      }

      override fun onAdFailedToShowFullScreenContent(
        fullScreenContentError: FullScreenContentError
      ) {
        // Rewarded interstitial ad failed to show.
        Log.e(TAG, "Rewarded interstitial ad failed to show: ${fullScreenContentError.message}")
      }

      override fun onAdImpression() {
        // Rewarded interstitial ad did record an impression.
      }

      override fun onAdClicked() {
        // Rewarded interstitial ad did record a click.
      }
    }
}

private void listenToAdEvents() {
  // Listen for ad events.
  if (rewardedInterstitialAd == null) {
    Log.e(TAG, "Rewarded interstitial ad is not ready yet.");
    return;
  }

  rewardedInterstitialAd.setAdEventCallback(
      new RewardedInterstitialAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded interstitial ad did show.
        }

        @Override
        public void onAdDismissedFullScreenContent() {
          // Rewarded interstitial ad did dismiss.
          rewardedInterstitialAd = null;
        }

        @Override
        public void onAdFailedToShowFullScreenContent(
            @NonNull FullScreenContentError fullScreenContentError) {
          // Rewarded interstitial ad failed to show.
          Log.e(
              TAG,
              "Rewarded interstitial ad failed to show: " + fullScreenContentError.getMessage());
        }

        @Override
        public void onAdImpression() {
          // Rewarded interstitial ad did record an impression.
        }

        @Override
        public void onAdClicked() {
          // Rewarded interstitial ad did record a click.
        }
      });
}

İsteğe bağlı: Sunucu tarafı doğrulama (SSV) geri çağırmalarını doğrulama

Uygulamanız sunucu tarafı doğrulama geri çağırmalarında ek veri gerektiriyorsa ödüllü geçiş reklamlarının özel veri özelliğini kullanın. Ödüllü geçiş reklamı nesnesinde ayarlanan herhangi bir dize değeri, SSV geri çağırmasının custom_data sorgu parametresine iletilir. Özel veri değeri ayarlanmamışsa custom_data sorgu parametresi değeri SSV geri çağırmasında yer almaz.

Aşağıdaki kod örneğinde, reklam gösterilmeden önce ödüllü geçiş reklamı nesnesinde özel verilerin nasıl ayarlanacağı gösterilmektedir:

RewardedInterstitialAd.load(
  context,
  AD_UNIT_ID,
  AdRequest.Builder().build(),
  object : RewardedInterstitialAdLoadCallback() {
    override fun onAdLoaded(ad: RewardedInterstitialAd) {
      rewardedInterstitialAd = ad
      val options =
        ServerSideVerificationOptions.Builder().setCustomData("SAMPLE_CUSTOM_DATA_STRING").build()
      rewardedInterstitialAd?.setServerSideVerificationOptions(options)
    }
  },
)

RewardedInterstitialAd.load(
    context,
    AD_UNIT_ID,
    new AdRequest.Builder().build(),
    new RewardedInterstitialAdLoadCallback() {
      @Override
      public void onAdLoaded(RewardedInterstitialAd ad) {
        rewardedInterstitialAd = ad;
        ServerSideVerificationOptions options =
            new ServerSideVerificationOptions.Builder()
                .setCustomData("SAMPLE_CUSTOM_DATA_STRING")
                .build();
        rewardedInterstitialAd.setServerSideVerificationOptions(options);
      }
    });

SAMPLE_CUSTOM_DATA_STRING öğesini özel verilerinizle değiştirin.

İsteğe bağlı: Önceden yükleme etkinliklerini dinleme

Reklamları önceden yüklemeye başladığınızda, reklamlar başarıyla önceden yüklendiğinde, önceden yüklenemediğinde veya reklam önbelleği tükendiğinde bildirim almak için önceden yükleme etkinliklerine kaydolun.

Aşağıdaki örnekte, önceden yükleme reklam etkinliklerine nasıl kaydolacağınız gösterilmektedir:

val preloadCallback =
  // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(
        TAG,
        "Rewarded interstitial preload ad $preloadId failed to load with error: ${adError.message}",
      )
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is not available")
      // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
    }

    override fun onAdPreloaded(preloadId: String, responseInfo: ResponseInfo) {
      Log.i(TAG, "Rewarded interstitial preload ad $preloadId is available")
    }
  }
val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback)

PreloadCallback preloadCallback =
    // [Important] Don't call ad preloader start() or pollAd() within the PreloadCallback.
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(@NonNull String preloadId, @NonNull LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded interstitial preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
        // [Optional] Get the error response info for additional details.
        // ResponseInfo responseInfo = adError.getResponseInfo();
      }

      @Override
      public void onAdsExhausted(@NonNull String preloadId) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is not available");
        // [Important] Don't call ad preloader start() or pollAd() from onAdsExhausted.
      }

      @Override
      public void onAdPreloaded(@NonNull String preloadId, @NonNull ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded interstitial preload ad " + preloadId + " is available");
      }
    };
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig, preloadCallback);

Bir reklam yüklenemediğinde GMA Next-Gen SDK, reklamları otomatik olarak önceden yükler ve önceden yüklenmiş yapılandırmalar için başarısız olan istekleri yeniden dener.

İsteğe bağlı: Reklamın kullanılabilirliğini kontrol edin

Bir reklamın kullanılabilir olup olmadığını öğrenmeniz gerekiyorsa reklamın kullanılabilirliğini kontrol edin. Aşağıdaki örnekte, önceden yüklenmiş bir reklamın kullanılabilir olup olmadığının nasıl kontrol edileceği gösterilmektedir:

private fun isAdAvailable(adUnitId: String): Boolean {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId)
}

private boolean isAdAvailable(String adUnitId) {
  return RewardedInterstitialAdPreloader.isAdAvailable(adUnitId);
}

İsteğe bağlı: Arabellek boyutunu ayarlama

Arabellek boyutu, bellekte tutulan önceden yüklenmiş reklamların sayısını kontrol eder. Google, varsayılan olarak bellek tüketimi ile reklam yayınlama gecikmesi arasında denge kurmak için arabellek boyutunu optimize eder. Bellekte tutulan reklam sayısını artırmak için özel bir arabellek boyutu ayarlayabilirsiniz. Maksimum arabellek boyutunun 4 olmasını öneririz.

Aşağıdaki örnekte, 4 önceden yüklenmiş reklamın arabellek boyutunun nasıl ayarlanacağı gösterilmektedir:

val adRequest = AdRequest.Builder(adUnitId).build()
// Maintain small or default buffer size unless rapid transitions are expected.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 4)
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig)

// Maintain small or default buffer size unless rapid transitions are expected.
AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 4);
RewardedInterstitialAdPreloader.start(adUnitId, preloadConfig);

Önceden yüklenen önbellek sınırları

GMA Next-Gen SDK, tüm reklam birimleri ve önceden yükleme kimliklerinde önceden yüklenen toplam reklam sayısıyla ilgili uygulama genelinde bir sınır uygular:

• Varsayılan sınır: Google, bellekte en fazla 6 önceden yüklenmiş reklam tutar. Bu sınır, tüm biçimler ve önceden yükleme kimlikleri arasında paylaşılır.
• Önceden yükleme kimliği başına 2 veya 3 arabellek boyutu tutmanızı öneririz.

İsteğe bağlı: Reklamların önceden yüklenmesini durdurma

Oturumda belirli bir önceden yükleme kimliği için reklam göstermeniz gerekmiyorsa reklamların önceden yüklenmesini durdurabilirsiniz. Belirli bir önceden yükleme kimliği için reklam yüklemeyi durdurmak üzere, destroy() yöntemini önceden yükleme kimliğiyle birlikte çağırın. destroy() yönteminin çağrılması, önceden yükleme kimliğiyle ilişkili tüm önceden yüklenmiş reklamları önbellekten kaldırır.

Aşağıdaki örnekte, reklamların önceden yüklenmesinin nasıl durdurulacağı gösterilmektedir:

private fun stopPreloading(adUnitId: String) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId)
}

private void stopPreloading(String adUnitId) {
  // Stops the preloading and destroy preloaded ads.
  RewardedInterstitialAdPreloader.destroy(adUnitId);
}

İsteğe bağlı: Yanıt bilgilerini okuyun

Reklamı önbellekten kaldırmadan sonraki önceden yüklenmiş reklamın yanıt bilgilerini okuyun.

Aşağıdaki örnekte, önceden yüklenen sonraki reklam yanıtı bilgilerinin nasıl okunacağı gösterilmektedir:

val responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId)
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.")
  return
}

Log.d(TAG, "Peeked ad response ID: ${responseInfo.responseId}")

ResponseInfo responseInfo = RewardedInterstitialAdPreloader.peekAdResponseInfo(preloadId);
if (responseInfo == null) {
  Log.e(TAG, "Failed to peek ad response info.");
  return;
}

Log.d(TAG, "Peeked ad response ID: " + responseInfo.getResponseId());