Ödüllü reklamlar


Ödüllü reklamlar, kullanıcılara uygulama içi ödüller karşılığında reklamlarla etkileşime geçme seçeneği sunar. Bu kılavuzda, Google Mobile Ads C++ SDK'sı kullanılarak ödüllü reklamların Android ve iOS uygulamalarına nasıl entegre edileceği gösterilmektedir.

Müşteri başarı hikayelerini okuyun: örnek olay 1, örnek olay 2.

Ön koşullar

  • Başlayın bölümünü tamamlayın.
  • (Yalnızca Android) JNI jobject referanslarıyla çalışma konusunda bilgi sahibi olmanız gerekir (Android JNI ipuçlarına bakın).

Her zaman test reklamlarıyla test yapın

Uygulamalarınızı oluşturup test ederken canlı üretim reklamları yerine test reklamları kullandığınızdan emin olun. Bunu yapmazsanız hesabınız askıya alınabilir.

Test reklamlarını yüklemenin en kolay yolu, ödüllü reklamlar için özel test reklam birimi kimliğimizi kullanmaktır. Bu kimlik, cihaz platformuna göre değişiklik gösterir:

  • Android: ca-app-pub-3940256099942544/5224354917
  • iOS: ca-app-pub-3940256099942544/1712485313

Bu reklamlar, her istek için test reklamları döndürecek şekilde özel olarak yapılandırılmıştır. Kodlama, test etme ve hata ayıklama sırasında kendi uygulamalarınızda bu reklamları kullanabilirsiniz. Uygulamanızı yayınlamadan önce bu kimliği kendi reklam birimi kimliğinizle değiştirdiğinizden emin olun.

Mobile Ads SDK'sının test reklamlarının işleyiş şekli hakkında daha fazla bilgi için Test Reklamları başlıklı makaleyi inceleyin.

Uygulama

Ödüllü reklamları entegre etmenin ana adımları şunlardır:

  1. Reklam yükleyin.
  2. Geri arama için kaydolun.
  3. Reklamı gösterin ve ödül etkinliğini yönetin.

RewardedAd yapılandırın

Ödüllü reklamlar RewardedAd nesnelerinde gösterilir. Bu nedenle, ödüllü reklamları uygulamanıza entegre etmenin ilk adımı bir RewardedAd örneği oluşturmak ve başlatmaktır.

  1. Uygulamanızın C++ koduna aşağıdaki üstbilgeyi ekleyin: 

     #include "firebase/gma/rewarded_ad.h"

  2. Bir RewardedAd nesnesi tanımlayıp örneklendirin: 

     firebase::gma::RewardedAd* rewarded_ad;
 rewarded_ad = new firebase::gma::RewardedAd();

  3. Üst görünümünüzü bir AdParent türüne yayınlayarak RewardedAd örneğini başlatın. Üst görünüm, Android Activity için bir JNI jobject referansı veya iOS UIView için bir işaretçidir.

    // my_ad_parent is a jobject reference to an Android Activity or
// a pointer to an iOS UIView.
firebase::gma::AdParent ad_parent =
  static_cast<firebase::gma::AdParent>(my_ad_parent);
firebase::Future<void> result = rewarded_ad->Initialize(ad_parent);

  4. Geleceği bir değişken olarak tutmaya alternatif olarak, RewardedAd nesnesinde InitializeLastResult() çağrısını yaparak başlatma işleminin durumunu düzenli olarak kontrol edebilirsiniz. Bu, genel oyun döngüsünüzdeki başlatma sürecini takip etmek için yararlı olabilir.

    // Monitor the status of the future in your game loop:
firebase::Future<void> result = rewarded_ad->InitializeLastResult();
if (result.status() == firebase::kFutureStatusComplete) {
  // Initialization completed.
  if(future.error() == firebase::gma::kAdErrorCodeNone) {
    // Initialization successful.
  } else {
    // An error has occurred.
  }
} else {
  // Initialization on-going.
}

firebase::Future ile çalışma hakkında daha fazla bilgi için Yöntem çağrılarının tamamlanma durumunu izlemek için Futures'i kullanma başlıklı makaleyi inceleyin.

Reklam yükleme

Reklam yükleme işlemi, RewardedAd nesnesinde LoadAd() yöntemi kullanılarak gerçekleştirilir. Yükleme yöntemi, RewardedAd nesnesini başlatmanızı, reklam birimi kimliğinizin ve bir AdRequest nesnenizin olmasını gerektirir. Yükleme işleminin durumunu ve sonucunu izlemek için kullanabileceğiniz bir firebase::Future döndürülür.

Aşağıdaki kodda, RewardedAd başarıyla başlatıldıktan sonra bir reklamın nasıl yükleneceği gösterilmektedir:

firebase::gma::AdRequest ad_request;
firebase::Future<firebase::gma::AdResult> load_ad_result;
load_ad_result = rewarded_ad->LoadAd(rewarded_ad_unit_id, ad_request);

Geri arama için kaydolun

Ödüllü reklam sunumu ve yaşam döngüsü etkinlikleriyle ilgili bildirimler almak için FullScreenContentListener sınıfını genişletmeniz gerekir. Özel FullScreenContentListener alt sınıfınız RewardedAd::SetFullScreenContentListener() yöntemi aracılığıyla kaydedilebilir. Reklam başarıyla veya başarısız bir şekilde sunulduğunda ve kapatıldığında bu sınıfa geri çağırma çağrıları gönderilir.

Aşağıdaki kodda, sınıfın nasıl genişletileceği ve reklama nasıl atanacağı gösterilmektedir:

  class ExampleFullScreenContentListener
      : public firebase::gma::FullScreenContentListener {

   public:
    ExampleFullScreenContentListener() {}

    void OnAdClicked() override {
      // This method is invoked when the user clicks the ad.
    }

    void OnAdDismissedFullScreenContent() override {
     // This method is invoked when the ad dismisses full screen content.
    }

    void OnAdFailedToShowFullScreenContent(const AdError& error) override {
      // This method is invoked when the ad failed to show full screen content.
      // Details about the error are contained within the AdError parameter.
    }

    void OnAdImpression() override {
      // This method is invoked when an impression is recorded for an ad.
    }

    void OnAdShowedFullScreenContent() override {
      // This method is invoked when the ad showed its full screen content.
    }
  };

  ExampleFullScreenContentListener* example_full_screen_content_listener =
    new ExampleFullScreenContentListener();
  rewarded_ad->SetFullScreenContentListener(example_full_screen_content_listener);

RewardedAd, tek kullanımlık bir nesnedir. Bu, ödüllü bir reklamın bir kez gösterildikten sonra tekrar gösterilemeyeceği anlamına gelir. En iyi uygulama, önceki reklam kapatıldıktan hemen sonra bir sonraki ödüllü reklamın yüklenmeye başlaması için FullScreenContentListener yönteminizin OnAdDismissedFullScreenContent() bölümüne başka bir ödüllü reklam yüklemektir.

Reklamı gösterme ve ödül etkinliğini işleme

Kullanıcılara ödüllü reklam göstermeden önce, ödül karşılığında ödüllü reklam içeriğini görüntüleme seçeneğini açıkça sunmanız gerekir. Ödüllü reklamlar her zaman isteğe bağlı bir deneyim olmalıdır.

Reklamınızı sunarken kullanıcıya verilecek ödülü işleyen bir UserEarnedReward nesnesi sağlamanız gerekir.

Aşağıdaki kodda, RewardedAd karakterinin nasıl gösterileceği gösterilmektedir:

// A simple listener track UserEarnedReward events.
class ExampleUserEarnedRewardListener :
    public firebase::gma::UserEarnedRewardListener {
 public:
   ExampleUserEarnedRewardListener() { }

  void OnUserEarnedReward(const firebase::gma::AdReward& reward) override {
    // Reward the user!
  }
};

ExampleUserEarnedRewardListener* user_earned_reward_listener =
  new ExampleUserEarnedRewardListener();
firebase::Future<void> result = rewarded_ad->Show(user_earned_reward_listener);

SSS

İlklendirme çağrısı için zaman aşımı var mı?
10 saniye sonra Google Mobile Ads C++ SDK'sı, bir uyumlulaştırma ağı ilk kullanıma hazırlama işlemini tamamlamamış olsa bile Initialize() tarafından döndürülen firebase::Future işlevini tamamlar.
İlklendirme geri çağırmasını aldığımda bazı uyumlulaştırma ağları hazır değilse ne olur?

Reklamları, SDK ilk kullanıma hazırlandıktan sonra yüklemek en iyi uygulamadır. Bir uyumlulaştırma ağı hazır olmasa bile Google Mobile Ads C++ SDK'sı bu ağdan reklam isteğinde bulunur. Bu nedenle, bir uyumlulaştırma ağı zaman aşımından sonra ilklendirmeyi tamamlarsa söz konusu oturumda gelecekteki reklam isteklerini yine sunabilir.

GetInitializationStatus() işlevini çağırarak uygulama oturumunuz boyunca tüm bağdaştırıcıların başlatma durumunu sorgulamaya devam edebilirsiniz.

Belirli bir uyumlulaştırma ağının neden hazır olmadığını nasıl öğrenebilirim?

AdapterStatus.description(), bir bağdaştırıcının reklam isteklerini yerine getirmeye hazır olmama nedenini açıklar. Uyumlulaştırma bağdaştırıcısı durumunu günlüğe kaydetme örneği için GitHub'daki örnek hızlı başlangıç uygulamamızın kaynak koduna bakın.

Ek kaynaklar

GitHub'daki örnek