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

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

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

Требования

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

Android 

ca-app-pub-3940256099942544/9257395921

iOS 

ca-app-pub-3940256099942544/5575463023

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

export function showPreloadedAppOpenAd(
  preloadId: string,
  customAdEventCallback?: FullScreenAdEventCallback,
) {
  if (!AppOpenAdPreloader.isAdAvailable(preloadId)) {
    console.log('No preloaded app open ad available right now.');
    return;
  }

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

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

  ad.show();
}

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

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

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

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

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

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

Использование менеджера на уровне приложения дает несколько ключевых преимуществ:

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

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

export class AppOpenAdManager {
  private adUnitId: string;
  private preloadId: string;
  private appStateSubscription?: NativeEventSubscription;
  private startTimeoutId?: ReturnType<typeof setTimeout>;

  constructor(adUnitId: string, preloadId: string) {
    this.adUnitId = adUnitId;
    this.preloadId = preloadId;
  }

  start(): boolean {
    if (!AppOpenAdPreloader.getConfiguration(this.preloadId)) {
      AppOpenAdPreloader.start(
        this.preloadId,
        {
          request: {adUnitId: this.adUnitId},
          bufferSize: 2,
        },
        {
          onAdPreloaded: (event) => {
            console.log(`App open ad preloaded for ${event.preloadId}`);
          },
          onAdFailedToPreload: (error: LoadAdError) => {
            console.error('Failed to preload app open ad:', error.message);
          },
          onAdsExhausted: () => {
            console.log('App open ad buffer exhausted.');
          },
        },
      );
    }

    if (!this.appStateSubscription && !this.startTimeoutId) {
      // Delay attaching the listener to ensure native dismissal transitions complete
      this.startTimeoutId = setTimeout(() => {
        this.startTimeoutId = undefined;
        if (!this.appStateSubscription) {
          this.appStateSubscription = AppState.addEventListener(
            'change',
            (nextAppState: AppStateStatus) => {
              if (nextAppState === 'active') {
                this.showAdIfAvailable();
              }
            },
          );
        }
      }, APP_STATE_LISTENER_DELAY_MS);
    }

    return true;
  }

  pause(): void {
    if (this.startTimeoutId) {
      clearTimeout(this.startTimeoutId);
      this.startTimeoutId = undefined;
    }
    this.appStateSubscription?.remove();
    this.appStateSubscription = undefined;
  }

  stop(): void {
    this.pause();
    AppOpenAdPreloader.destroy(this.preloadId);
  }

  showAdIfAvailable() {
    if (!AppOpenAdPreloader.isAdAvailable(this.preloadId)) {
      console.log('App open ad is not preloaded or available right now.');
      return;
    }

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

    // Pause listener while presenting the ad
    this.pause();

    ad.adEventCallback = {
      onAdShowedFullScreenContent: () => {
        console.log('Preloaded app open ad showed full screen content.');
      },
      onAdDismissedFullScreenContent: () => {
        console.log('Preloaded app open ad dismissed full screen content.');
        ad.destroy();
        this.start();
      },
      onAdFailedToShowFullScreenContent: (error) => {
        console.error('Failed to show preloaded app open ad:', error);
        ad.destroy();
        this.start();
      },
    };

    ad.show();
  }
}

Как отслеживать события перехода приложения в активный режим

Чтобы показывать объявления, когда приложение возвращается на передний план, зарегистрируйте прослушиватель change в модуле AppState в корневом компоненте приложения, например App.tsx. Проверьте, когда состояние изменится на active. Например, вызовите метод start в экземпляре менеджера рекламы в компоненте App.tsx.

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

  1. Удалите прослушиватель событий AppState, прежде чем показывать полноэкранное объявление.
  2. Чтобы прослушивание возобновлялось независимо от того, закрыл ли пользователь объявление или оно не было показано, снова добавьте прослушиватель событий AppState в обратные вызовы onAdDismissedFullScreenContent и onAdFailedToShowFullScreenContent.

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

Узнайте о холодных запусках и экранах загрузки

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

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

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

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

export function destroyAppOpenAdPreloader(preloadId: string) {
  AppOpenAdPreloader.destroy(preloadId);
}

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

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

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

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

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

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

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

  const handleShowAd = () => {
    setStatus('Showing preloaded ad...');
    showPreloadedAppOpenAd(PRELOAD_ID, {
      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 App Open Ads</Text>
      <Text style={styles.status}>Status: {status}</Text>
      <Text style={styles.status}>Ads Available: {numAdsAvailable}</Text>
      <View style={styles.buttonGroup}>
        <Button
          title="Show Preloaded Ad"
          onPress={handleShowAd}
          disabled={numAdsAvailable === 0}
        />
      </View>
    </View>
  );
}

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

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

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

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