Geri bildiriminizi paylaşın ve Google Mobile Ads SDK'sı yol haritasının şekillendirilmesine yardımcı olun. 5 Mayıs 2023'te sona ermeden önce 2023 Google Mobile Ads SDK'sı Yıllık Anketi'ne katılın.

Ödüllü reklamlar

Ödüllü reklamlar, kullanıcıların uygulama içi ödüller karşılığında onlarla etkileşime geçmelerine imkan sağlar. Bu kılavuz, Google Mobile Ads C++ SDK'sını kullanarak ödüllü reklamları Android ve iOS uygulamalarına nasıl entegre edeceğinizi gösterir.

Bazı müşteri başarı öykülerini okuyun: örnek olay 1, örnek olay 2.

Ön koşullar

Her zaman test reklamlarıyla test edin

Uygulamalarınızı oluştururken ve test ederken yayında olan üretim reklamları yerine test reklamlarını kullandığınızdan emin olun. Aksi takdirde hesabınız askıya alınabilir.

Test reklamlarını yüklemenin en kolay yolu, ödüllü reklam 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

Bunlar, 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 işlemleri sırasında bunları kendi uygulamalarınızda kullanabilirsiniz. Uygulamanızı yayınlamadan önce kendi reklam birimi kimliğinizle değiştirmeniz yeterlidir.

Mobile Ads SDK'sının test reklamlarının işleyiş şekli hakkında daha fazla bilgi edinmek için Test Reklamları bölümüne bakın.

Uygulama

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

  1. Bir reklam yükleyin.
  2. Geri çağırma için kaydolun.
  3. Reklamı görüntüleyin ve ödül etkinliğini yönetin.

RewardedAd yapılandırın

Ödüllü reklamlar RewardedAd nesnesinde gösterilir. Dolayısıyla, ödüllü reklamları uygulamanıza entegre etmenin ilk adımı RewardedAd örneği oluşturup başlatmaktır.

  1. Aşağıdaki başlığı uygulamanızın C++ koduna ekleyin: 

     #include "firebase/gma/rewarded_ad.h"

  2. Bir RewardedAd nesnesi belirleyip beyan edin: 

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

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

    // 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. Değişken olarak geleceği saklamaya alternatif olarak, RewardedAd nesnesine InitializeLastResult() işlevi çağırarak ilk kullanıma hazırlama işleminin durumunu belirli aralıklarla kontrol edebilirsiniz. Bu, genel oyun döngünüzdeki ilk kullanıma hazırlama sürecini takip etmek için faydalı 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 Vadeli İşlemler'i kullanma konusuna bakın.

Reklam yükleme

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

RewardedAd başarıyla başlatıldıktan sonra reklamın nasıl yükleneceğini aşağıdaki kodda görebilirsiniz:

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 çağırma için kaydolun

Ödüllü reklam sunumu ve yaşam döngüsü olaylarıyla ilgili bildirim almak için FullScreenContentListener sınıfını artırmanız gerekir. Özel FullScreenContentListener alt sınıfınız RewardedAd::SetFullScreenContentListener() yöntemiyle kaydedilebilir ve reklam başarıyla veya başarısız olarak sunulduğunda ve kapatıldığında geri çağırmalar alır.

Aşağıdaki kod, sınıfın nasıl genişletileceğini ve reklama nasıl atanacağını gösterir:

  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österilmeyeceği anlamına gelir. En iyi uygulama, FullScreenContentListener ödülünüzün OnAdDismissedFullScreenContent() yönteminde başka bir ödüllü reklam yüklemektir. Böylece bir sonraki ödüllü reklam, önceki reklam kapatıldığı anda yüklenmeye başlar.

Reklamı gösterin ve ödül etkinliğini yönetin

Kullanıcılara ödüllü reklam göstermeden önce, ödüllü reklam içeriğini ödül karşılığında görüntülemeniz için kullanıcıya açık bir seçenek sunmalısınız. Ödüllü reklamlar her zaman isteğe bağlı olmalıdır.

Reklamınızı sunarken, kullanıcının ödülünü işlemek için bir UserEarnedReward nesnesi sağlamanız gerekir.

Aşağıdaki kod, RewardedAd öğesinin nasıl gösterileceğini gösterir:

// 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

Başlatma ç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ırlamayı henüz tamamlamamış olsa bile Initialize() tarafından döndürülen firebase::Future işlemini tamamlar.
İlk kullanıma hazırlama geri çağırması aldığımda bazı uyumlulaştırma ağları hazır değilse ne olur?

SDK başlatma işlemi tamamlandıktan sonra reklam yüklemek en iyi uygulamadır. Uyumlulaştırma ağı hazır olmasa bile Google Mobile Ads C++ SDK'sı yine de ağdan reklam ister. Bu nedenle, bir uyumlulaştırma ağı zaman aşımından sonra ilk kez başlatılırsa bu oturumda gelecekte yapılacak reklam isteklerine yine de hizmet verebilir.

GetInitializationStatus() çağırarak uygulama oturumunuz genelinde tüm bağdaştırıcıların ilk kullanıma hazırlama 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 isteklerine neden hizmet vermeye hazır olmadığını açıklar. Uyumlulaştırma bağdaştırıcısı durumunu günlüğe kaydetme örneğini görmek için GitHub'daki örnek hızlı başlangıç uygulamamızın kaynak koduna bakın.

Ek kaynaklar

GitHub'da örnek