Ödüllü reklamları ayarlama

Platform seçin: Android iOS Unity Flutter Android (Eski)

Ödüllü reklamlar video reklamlar, oynanabilir reklamlar ve anketlerle etkileşimde bulunan kullanıcıları uygulama içi öğelerle ödüllendirmenize olanak tanır.

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

Başlamadan önce

Devam etmeden önce şunları yapın:

  • Kurulum GMA Next-Gen SDK.
  • ca-app-pub-3940256099942544/5224354917 test ödüllü reklam birimi kimliğini kullanın.
    • Uygulamanızı oluştururken ve test ederken, yayındaki üretim reklamları yerine test reklamlarını kullandığınızdan emin olun. Test reklam birimi kimliğini kullanmazsanız Google, hesabınızı askıya alabilir.
    • 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 (beta) anlama

GMA Next-Gen SDK'da reklam ön yüklemesi, reklam yükleme ve önbelleğe alma işlemlerini otomatikleştirir.

Reklam ön yüklemesi 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.
  • Süre sonu işleme: Süresi dolmadan önce reklamları 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 GMA Next-Gen SDK ilk kullanıma hazırlanırken start yöntemini bir kez çağırın. start yöntemini çağırdıktan sonra GMA Next-Gen SDK, reklamları otomatik olarak önceden yükler ve önceden yüklenmiş yapılandırmalar için başarısız istekleri yeniden dener.

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

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
val preloadConfig = PreloadConfiguration(adRequest)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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. Ön yükleme kimliği, reklam ön yükleme yapılandırmasını tanımlamak için oluşturduğunuz bir 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ısı iletin.

Reklam ön yüklemesi, hedefleme parametrelerinin veya reklam isteklerinin değiştirilmesini desteklemez. İstekler arasında hedefleme parametrelerini değiştirmeniz gerekiyorsa tekli yükleme'yi kullanın.

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

Reklamı göstermeden önce pollAd yöntemini çağırın. Önceden yüklenmiş reklam nesnesini depolamayın. pollAd yöntemini çağırdığınızda GMA Next-Gen SDK, kullanılabilir bir reklamı alır ve arka planda bir sonraki reklamı otomatik olarak önceden yükler. Kullanılabilir 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ınıp gösterileceği açıklanmaktadır:

Kotlin

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

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

Java

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

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

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

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

Uygulamanız bir reklam yerleşimine ulaştığında ve show yöntemini çağırabildiğinde pollAd yöntemini çağırın. Reklamı bekletmek için önceden yükleme geri çağırmalarında veya isAdAvailable yöntemini kontrol ettikten sonra pollAd yöntemini çağırmayın. Reklamı göstermeden önce reklam meta verilerini incelemeniz gerekiyorsa reklamı önbellekten kaldırmadan yanıt bilgilerini okuyun.

Reklam etkinliklerini dinleme

Reklamı göstermeden önce reklam etkinliklerini dinleyin. Aşağıdaki örnekte, reklam etkinlikleri için geri çağırmalar kaydedilmektedir:

Kotlin

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

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

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

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

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

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

Java

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

  rewardedAd.setAdEventCallback(
      new RewardedAdEventCallback() {
        @Override
        public void onAdShowedFullScreenContent() {
          // Rewarded ad did show.
        }

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

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

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

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

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

Sunucu tarafı doğrulama (SSV) geri çağırmalarında kullanıcı ve uygulama bağlamını iletmek için reklamı göstermeden önce reklam nesnesinde doğrulama seçeneklerini ayarlayın. SSV geri çağırmaları, sunucunuza Google'dan oturum durumu olmadan ulaştığı için aşağıdaki isteğe bağlı dizeleri ekleyin. Google, bu dizeleri SSV geri çağırmasında imzalı sorgu parametreleri olarak değiştirilmeden iletir.

  • user_id sorgu parametresi: Kredi verilecek kullanıcıyı tanımlar (ör. dahili hesap kimliği).
  • custom_data sorgu parametresi: Ödül yerleşimi, oyun seviyesi veya sunucu tarafından oluşturulan tek seferlik rastgele sayı gibi uygulama verilerini taşır.

Bir değer ayarlamazsanız Google, bu sorgu parametresini SSV geri çağırmasından çıkarır.

Aşağıdaki örnekte, reklam gösterilmeden önce bir reklam nesnesinde özel veriler ayarlanmaktadır:

Kotlin

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

Java

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

SAMPLE_CUSTOM_DATA_STRING değerini kendi özel verilerinizle değiştirin.

Önemli nokta: custom_data sorgu parametresi yüzde kodlamalıdır. Değeri ayrıştırmadan önce sunucunuzda dizeyi URL kod çözme işlemine tabi tutun ve user_id veya custom_data sorgu parametrelerine güvenmeden önce geri çağırma imzasını doğrulayın.

İsteğe bağlı: Ön 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 ön yükleme etkinliklerine kaydolun.

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

Kotlin

val preloadCallback =
  object : PreloadCallback {
    override fun onAdFailedToPreload(preloadId: String, adError: LoadAdError) {
      Log.d(TAG, "Rewarded preload ad $preloadId failed to load with error: ${adError.message}")
    }

    override fun onAdsExhausted(preloadId: String) {
      Log.i(TAG, "Rewarded preload ad $preloadId is not available")
    }

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

Java

PreloadCallback preloadCallback =
    new PreloadCallback() {
      @Override
      public void onAdFailedToPreload(String preloadId, LoadAdError adError) {
        Log.d(
            TAG,
            String.format(
                "Rewarded preload ad %s failed to load with error: %s",
                preloadId, adError.getMessage()));
      }

      @Override
      public void onAdsExhausted(String preloadId) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is not available");
      }

      @Override
      public void onAdPreloaded(String preloadId, ResponseInfo responseInfo) {
        Log.i(TAG, "Rewarded preload ad " + preloadId + " is available");
      }
    };

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest);
RewardedAdPreloader.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 istekleri yeniden dener. Başarısız geri çağırmalarda manuel yükleme isteklerini çağırmayın. Ön yükleme etkinliği geri çağırma yöntemlerinde pollAd, destroy veya start yöntemlerini çağırmayın. Bu yöntemleri geri çağırmalarda çağırmak, yinelemeli yükleme döngülerini çağırabilir.

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

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 mevcut olup olmadığı kontrol edilmektedir:

Kotlin

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

Java

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

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

Arabellek boyutu, bellekte tutulan önceden yüklenmiş reklamların sayısını kontrol eder. Google, bellek tüketimini ve reklam sunma gecikmesini dengelemek için arabellek boyutunu varsayılan olarak optimize eder. Bellekte tutulan reklam sayısını artırmak veya azaltmak için özel bir arabellek boyutu ayarlayabilirsiniz. Önceden yüklenmiş iki reklamlık bir arabellek boyutu öneririz. Trafiğinizin çoğu düşük bellekli cihazlardan geliyorsa arabellek boyutunu küçültün.

Aşağıdaki örnekte arabellek boyutunun nasıl ayarlanacağı gösterilmektedir:

Kotlin

val adRequest = AdRequest.Builder(adUnitId).build()
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
val preloadConfig = PreloadConfiguration(adRequest, bufferSize = 2)
RewardedAdPreloader.start(adUnitId, preloadConfig)

Java

AdRequest adRequest = new AdRequest.Builder(adUnitId).build();
// Define a PreloadConfiguration and set the buffer size to 2 preloaded ads.
PreloadConfiguration preloadConfig = new PreloadConfiguration(adRequest, 2);
RewardedAdPreloader.start(adUnitId, preloadConfig);

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

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

  • Varsayılan sınır: Google, bellekte en fazla altı önceden yüklenmiş reklam tutar. Bu sınır, tüm biçimler ve önceden yükleme kimlikleri arasında paylaşılır.
  • Her önceden yükleme kimliği için iki arabellek boyutu kullanmanızı öneririz.

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

Uygulamanız reklam yayınlarken önceden yüklemeyi etkin tutun. Bu süre boyunca destroy yöntemini kullanmayın. Oturumda belirli bir önceden yükleme kimliği için tekrar reklam göstermeniz gerekmiyorsa reklamları önceden yüklemeyi durdurabilirsiniz. Belirli bir önceden yükleme kimliği için reklam yüklemeyi durdurmak istiyorsanız önceden yükleme kimliğiyle destroy yöntemini çağırın. destroy yöntemini çağırmak, önceden yükleme kimliğiyle ilişkili önceden yüklenmiş tüm reklamları önbellekten kaldırır.

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

Kotlin

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

Java

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

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

Önceden yüklenmiş bir sonraki reklamın yanıt bilgilerini, reklamı önbellekten kaldırmadan okuyun. Reklam göstermeden önce reklam meta verilerini incelemeniz gerekiyorsa pollAd yöntemini çağırmak yerine yanıt bilgilerini okuyun.

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

Kotlin

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

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

Java

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

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