Как настроить объявления с вознаграждением

Выберите платформу: Android iOS Unity Flutter Android (устаревшая версия)

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

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

Подготовка

Прежде чем продолжить, выполните следующие действия:

  • Настройте GMA Next-Gen SDK.
  • Используйте тестовый идентификатор рекламного блока для объявлений с вознаграждением ca-app-pub-3940256099942544/5224354917.
    • При создании и тестировании приложения используйте тестовые объявления, а не реальные. Если вы не будете использовать идентификатор тестового рекламного блока, Google может заблокировать ваш аккаунт.
    • Перед публикацией приложения замените этот идентификатор на идентификатор рекламного блока.
    • Подробнее GMA Next-Gen SDK о включении тестовых объявлений…

Предварительная загрузка объявлений (бета)

Предварительная загрузка объявлений в GMA Next-Gen SDK автоматизирует загрузку и кеширование объявлений.

Предварительная загрузка объявлений дает следующие преимущества:

  • Управление ссылками. Ссылки сохраняются до показа объявлений.
  • Автоматическая перезагрузка. Новое объявление загружается, когда одно из них извлекается из кеша.
  • Управляемые повторные попытки. Если не удается загрузить объявление, выполняется повторная попытка.
  • Обработка истечения срока действия. Объявления обновляются до истечения срока действия.
  • Оптимизация кеша. Порядок кеширования оптимизируется так, чтобы показывать объявления с наивысшим приоритетом.
Примечание. Чтобы загружать объявления вручную, ознакомьтесь с разделом Загрузка одного объявления с вознаграждением.

Как начать предварительную загрузку объявлений

Чтобы начать предварительную загрузку объявлений, вызовите метод start один раз при запуске приложения. После вызова метода start GMA Next-Gen SDK автоматически выполняется предварительная загрузка объявлений и повторные попытки выполнить неудачные запросы для предварительно загруженных конфигураций.

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

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 идентификатором рекламного блока.

В предыдущем примере показано, как использовать идентификатор рекламного блока в качестве идентификатора предварительной загрузки. Идентификатор предварительной загрузки – это строка, которую вы создаете, чтобы идентифицировать конфигурацию предварительной загрузки объявлений. Если для одного и того же идентификатора рекламного блока в вашем приложении требуется несколько конфигураций таргетинга, передайте специальный строковый идентификатор.

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

Чтобы показать объявление, вызовите метод pollAd. GMA Next-Gen SDK получает доступное объявление и автоматически загружает следующее в фоновом режиме. Если объявление недоступно, GMA Next-Gen SDK не возвращает никаких объявлений.

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

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

Пока вы не будете готовы показывать объявление, не вызывайте метод pollAd. Чтобы прочитать информацию об ответе на объявление, не показывая его, ознакомьтесь с разделом Как прочитать информацию об ответе.

Как отслеживать события объявлений

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

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

Как проверить обратные вызовы при проверке на стороне сервера (необязательно)

Если для проверки на стороне сервера в вашем приложении требуются дополнительные данные, используйте функцию специальных данных в объявлениях. Серверы объявлений Google передают любое строковое значение, заданное в объекте объявления, в параметр запроса custom_data обратного вызова SSV. Если значение пользовательских данных не задано, то значение параметра запроса custom_data не будет представлено в обратном вызове для проверки на стороне сервера.

В следующем примере показано, как задать специальные данные для объекта объявления до его показа:

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 собственными данными.

Как отслеживать события предзагрузки (необязательно)

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

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

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

Если объявление не загружается, GMA Next-Gen SDK автоматически предзагружает объявления и повторяет неудачные запросы для предзагруженных конфигураций.

Как проверить доступность объявления (необязательно)

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

Kotlin

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

Java

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

Как задать размер буфера (необязательно)

Размер буфера определяет количество предварительно загруженных объявлений, хранящихся в памяти. По умолчанию Google оптимизирует размер буфера, чтобы сбалансировать потребление памяти и задержку показа рекламы. Вы можете задать собственный размер буфера, чтобы увеличить количество объявлений, хранящихся в памяти. Мы рекомендуем использовать буфер, в котором будет два предварительно загруженных объявления.

В следующем примере показано, как задать размер буфера:

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

Лимиты предварительной загрузки кеша

GMA Next-Gen SDK устанавливает ограничение на общее количество предварительно загруженных объявлений в приложении для всех рекламных блоков и идентификаторов предварительной загрузки:

  • По умолчанию в памяти Google хранится не более шести предварительно загруженных объявлений. Это ограничение распространяется на все форматы и идентификаторы предварительной загрузки.
  • Мы рекомендуем задать для каждого идентификатора предзагрузки размер буфера, равный двум.

Как отключить предварительную загрузку рекламы (необязательно)

Если вам не нужно показывать объявления с определенным идентификатором предварительной загрузки в течение сеанса, вы можете остановить предварительную загрузку. Чтобы прекратить загрузку объявлений для определенного идентификатора предварительной загрузки, вызовите метод destroy с этим идентификатором. Вызов метода destroy удаляет из кеша все предварительно загруженные объявления, связанные с идентификатором предварительной загрузки.

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

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

Как прочитать информацию об ответах (необязательно)

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

В примере ниже показано, как получить информацию о следующем предварительно загруженном объявлении:

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