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

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

Чтобы устранить задержку при показе и обеспечить доступность объявления, когда пользователь получает вознаграждение, Google Mobile Ads SDK for React Native использует предварительную загрузку объявлений для управления фоновой загрузкой, кешированием и пополнением буфера.

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

Требования

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

Android 

ca-app-pub-3940256099942544/5224354917

iOS 

ca-app-pub-3940256099942544/1712485313

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

Предварительная загрузка объявлений в Google Mobile Ads SDK for React Native автоматизирует загрузку и кеширование объявлений.

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

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

Чтобы загружать объявления вручную, ознакомьтесь с разделом Загрузка одного объявления с вознаграждением.

Начать предварительную загрузку

Чтобы начать предварительную загрузку объявлений, вызовите метод RewardedAdPreloader.start и передайте значение preloadId, настройки конфигурации и обратные вызовы событий, чтобы отслеживать изменения состояния буфера:

export function startRewardedAdPreloader(
  adUnitId: string,
  preloadId: string,
  customPreloadCallback?: PreloadCallback,
): boolean {
  const started = RewardedAdPreloader.start(
    preloadId,
    {
      request: {adUnitId},
      bufferSize: 2,
    },
    {
      // Called when an ad is preloaded into the buffer.
      onAdPreloaded: (event) => {
        console.log(`Rewarded ad preloaded for ${event.preloadId}`);
        customPreloadCallback?.onAdPreloaded?.(event);
      },
      // Called when an ad fails to preload.
      onAdFailedToPreload: (error: LoadAdError) => {
        console.error('Failed to preload rewarded ad:', error.message);
        customPreloadCallback?.onAdFailedToPreload?.(error);
      },
      // Called when all preloaded ads in the buffer have been shown.
      onAdsExhausted: () => {
        console.log('Rewarded ad buffer exhausted.');
        customPreloadCallback?.onAdsExhausted?.();
      },
    },
  );
  return started;
}

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

Когда приложение запрашивает предварительно загруженное объявление из буфера, Google Mobile Ads SDK for React Native запрашивает замену в фоновом режиме, чтобы пополнить буфер. Если в буфере не осталось предварительно загруженных объявлений, Google Mobile Ads SDK for React Native вызывает onAdsExhausted.

Ограничения на предварительное кеширование

Google Mobile Ads SDK for React Native ограничивает общее количество предварительно загруженных объявлений во всех рекламных блоках и идентификаторах предварительной загрузки:

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

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

Опрос и показ объявления

Перед показом объявления убедитесь, что оно доступно, вызвав метод RewardedAdPreloader.isAdAvailable. Чтобы получить объявление, вызовите метод RewardedAdPreloader.pollAd.

Чтобы отслеживать события показа, например закрытие объявления или сбой показа, задайте свойство adEventCallback в экземпляре объявления, прежде чем вызывать метод show:

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

export function showPreloadedRewardedAd(
  preloadId: string,
  onRewardEarned: (reward: Reward) => void,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!RewardedAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded rewarded ad available right now.');
    return;
  }

  const ad = RewardedAdPreloader.pollAd(preloadId);
  if (!ad) {
    return;
  }

  ad.adEventCallback = {
    // Called when the ad is presented on screen.
    onAdShowedFullScreenContent: () => {
      console.log('Preloaded rewarded ad showed full screen content.');
      customAdEventCallback?.onAdShowedFullScreenContent?.();
    },
    // Called when the ad is closed by the user.
    onAdDismissedFullScreenContent: () => {
      console.log('Preloaded rewarded ad dismissed full screen content.');
      customAdEventCallback?.onAdDismissedFullScreenContent?.();
      ad.destroy();
    },
    // Called when presentation fails.
    onAdFailedToShowFullScreenContent: (error) => {
      console.error('Failed to show preloaded rewarded ad:', error);
      customAdEventCallback?.onAdFailedToShowFullScreenContent?.(error);
      ad.destroy();
    },
    // Called when an impression is recorded.
    onAdImpression: () => {
      console.log('Preloaded rewarded ad recorded an impression.');
      customAdEventCallback?.onAdImpression?.();
    },
    // Called when the user taps the ad.
    onAdClicked: () => {
      console.log('Preloaded rewarded ad was clicked.');
      customAdEventCallback?.onAdClicked?.();
    },
    // Called when the ad is estimated to have earned money.
    onAdPaid: (adValue) => {
      console.log(
        `Preloaded rewarded ad paid: ${adValue.amountMicros}` +
          ` ${adValue.currencyCode}`,
      );
      customAdEventCallback?.onAdPaid?.(adValue);
    },
  };

  ad.show(onRewardEarned);
}

Чтобы освободить память и ресурсы, вызовите метод ad.destroy в обратных вызовах onAdDismissedFullScreenContent и onAdFailedToShowFullScreenContent.

Прочитайте информацию об ответе

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

export function peekRewardedAdResponseInfo(
  preloadId: string,
): ResponseInfo | null {
  const responseInfo = RewardedAdPreloader.peekAdResponseInfo(preloadId);
  if (responseInfo) {
    console.log('Next preloaded rewarded ad response info:', responseInfo);
  }
  return responseInfo;
}

Если объявление доступно, метод peekAdResponseInfo возвращает объект ResponseInfo, содержащий информацию о загруженном источнике объявления и сетевых адаптерах.

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

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

Заданные вами значения передаются в параметры запроса обратного вызова для проверки на стороне сервера:

  • userId: передается в параметр запроса user_id для идентификации пользователя.
  • customData – передает параметр запроса custom_data для пересылки специальных метаданных.

В примере ниже для объекта объявления с вознаграждением перед показом объявления задаются параметры ServerSideVerificationOptions (customData и userId).

export function setServerSideVerificationRewarded(ad: RewardedAd) {
  ad.serverSideVerificationOptions = {
    userId: 'user_123',
    customData: 'sample_custom_data',
  };
}

Очистка ресурсов

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

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

export function destroyRewardedAdPreloader(preloadId: string) {
  RewardedAdPreloader.destroy(preloadId);
}

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

Посмотреть полный пример

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

export function RewardedScreen() {
  const [numAdsAvailable, setNumAdsAvailable] = useState<number>(0);
  const [status, setStatus] = useState<string>('Preloader idle.');
  const [reward, setReward] = useState<string | null>(null);

  const refreshAdCount = () => {
    const count = RewardedAdPreloader.getNumAdsAvailable(PRELOAD_ID);
    setNumAdsAvailable(count);
  };

  useEffect(() => {
    // Start preloading ads on component mount
    const started = startRewardedAdPreloader(REWARDED_AD_UNIT_ID, PRELOAD_ID, {
      onAdPreloaded: () => {
        refreshAdCount();
        setStatus('Rewarded ad preloaded into buffer.');
      },
      onAdFailedToPreload: (error) => {
        setStatus(`Failed to preload rewarded ad: ${error.message}`);
      },
      onAdsExhausted: () => {
        refreshAdCount();
        setStatus('Preload buffer exhausted for rewarded ads.');
      },
    });
    if (started) {
      setStatus('Preloader started.');
    }

    // Clean up preloader resources on component unmount
    return () => {
      destroyRewardedAdPreloader(PRELOAD_ID);
    };
  }, []);

  const handleShowAd = () => {
    setReward(null);
    setStatus('Showing preloaded ad...');
    showPreloadedRewardedAd(
      PRELOAD_ID,
      (userReward) => {
        setReward(`${userReward.amount} ${userReward.type}`);
      },
      {
        onAdDismissedFullScreenContent: () => {
          setStatus('Ad dismissed.');
        },
        onAdFailedToShowFullScreenContent: (error) => {
          setStatus(`Failed to show preloaded ad: ${error.message}`);
        },
      },
    );
    refreshAdCount();
  };

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Preload Rewarded Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      {reward && <Text style={styles.rewardText}>Earned: {reward}</Text>}
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

Замените следующее:

  • REWARDED_AD_UNIT_ID на идентификатор рекламного блока.
  • PRELOAD_ID – идентификатор предзагрузчика.

Дальнейшие действия

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