Объявления с вознаграждением


Объявления с вознаграждением позволяют пользователям взаимодействовать с ними в обмен на вознаграждения в приложении. В этом руководстве рассказывается, как интегрировать объявления с вознаграждением в приложения для Android и iOS с помощью Google Mobile Ads C++ SDK.

Прочитайте истории успеха наших клиентов: история 1, история 2.

Требования

Всегда используйте тестовые объявления

При создании и тестировании приложений используйте тестовые объявления, а не реальные. В противном случае ваш аккаунт может быть заблокирован.

Проще всего загрузить тестовые объявления с вознаграждением, используя специальный идентификатор тестового рекламного блока. Он зависит от платформы устройства:

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

Они специально настроены так, чтобы возвращать тестовые объявления по каждому запросу. Вы можете использовать их в своих приложениях при написании кода, тестировании и отладке. Не забудьте заменить его идентификатором своего рекламного блока перед публикацией приложения.

Подробнее о том, как работают тестовые объявления Mobile Ads SDK, читайте в статье Тестовые объявления.

Реализация

Основные этапы интеграции объявлений с вознаграждением:

  1. Загрузите объявление.
  2. Зарегистрируйте обратные вызовы.
  3. Покажите объявление и обработайте событие получения вознаграждения.

Настроить RewardedAd

Объявления с вознаграждением показываются в объектах RewardedAd, поэтому сначала нужно создать и инициализировать экземпляр RewardedAd.

  1. Добавьте в код C++ приложения следующий заголовок: 

     #include "firebase/gma/rewarded_ad.h"

  2. Объявите и создайте экземпляр объекта RewardedAd: 

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

  3. Инициализируйте экземпляр RewardedAd, используя родительское представление, приведенное к типу AdParent. Родительский элемент просмотра – это ссылка JNI jobject на Android Activity или указатель на iOS UIView.

    // 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. Вместо того чтобы сохранять future в качестве переменной, вы можете периодически проверять статус операции инициализации, вызывая InitializeLastResult() для объекта RewardedAd. Это может быть полезно для отслеживания процесса инициализации в глобальном игровом цикле.

    // 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, читайте в статье Как использовать Futures для отслеживания статуса выполнения вызовов методов.

Загрузка объявления

Загрузка объявления выполняется с помощью метода LoadAd() объекта RewardedAd. Для метода load требуется инициализировать объект RewardedAd, а также указать идентификатор рекламного блока и объект AdRequest. Возвращается объект firebase::Future, который можно использовать для отслеживания состояния и результата операции загрузки.

В приведенном ниже коде показано, как загрузить объявление после успешной инициализации RewardedAd.

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);

Регистрация обратных вызовов

Чтобы получать уведомления о показе объявлений с вознаграждением и событиях жизненного цикла, необходимо расширить класс FullScreenContentListener. Собственный подкласс FullScreenContentListener можно зарегистрировать с помощью метода RewardedAd::SetFullScreenContentListener(). Он будет получать обратные вызовы при успешном или неуспешном показе объявления, а также при его закрытии.

В приведенном ниже коде показано, как расширить класс и назначить его объявлению.

  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 – это одноразовый объект. Это означает, что после показа объявления с вознаграждением оно не может быть показано снова. Рекомендуется загружать следующее объявление с вознаграждением в методе OnAdDismissedFullScreenContent() объекта FullScreenContentListener, чтобы оно начало загружаться сразу после закрытия предыдущего.

Показ объявления и обработка события получения вознаграждения

Перед показом объявления с вознаграждением пользователь должен увидеть предложение просмотреть содержание объявления с вознаграждением в обмен на награду. Объявления с вознаграждением должны показываться только с согласия пользователя.

При показе объявления необходимо предоставить объект UserEarnedReward, который будет обрабатывать вознаграждение для пользователя.

В примере кода ниже показано, как отобразить RewardedAd.

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

Часто задаваемые вопросы

Есть ли тайм-аут для вызова инициализации?
Через 10 секунд Google Mobile Ads C++ SDK завершает firebase::Future, возвращенный Initialize(), даже если сеть медиации ещё не завершила инициализацию.
Что делать, если некоторые сети медиации не готовы, когда я получаю обратный вызов инициализации?

Рекомендуем загружать объявления после завершения инициализации SDK. Даже если сеть медиации не готова, Google Mobile Ads C++ SDK все равно запросит у нее объявление. Если сеть медиации завершит инициализацию после истечения времени ожидания, она все равно сможет обрабатывать будущие запросы объявлений в этом сеансе.

Вы можете продолжать опрашивать статус инициализации всех адаптеров на протяжении сеанса приложения, вызывая GetInitializationStatus().

Как узнать, почему сеть медиации не готова?

AdapterStatus.description() описывает, почему адаптер не готов обрабатывать запросы объявлений. Пример регистрации статуса адаптера медиации можно найти в исходном коде нашего примера приложения для быстрого старта на GitHub.

Дополнительные ресурсы

Пример на GitHub