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


Объявления с вознаграждением позволяют пользователям взаимодействовать с рекламой в обмен на вознаграждения в приложении. В этом руководстве рассказывается, как интегрировать объявления с вознаграждением в приложения для 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. Для метода загрузки требуется, чтобы вы инициализировали объект 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