Как реализовать объявления с функцией "Картинка в картинке" (бета-версия)

Выберите платформу: Android iOS Unity

Картинка в картинке

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

В этом руководстве рассказывается, как запрашивать и показывать объявления в режиме "картинка в картинке" в приложении с помощью Google Mobile Ads SDK.

Подготовка

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

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

Чтобы загрузить объект GADPictureInPictureAd, создайте запрос объявления и вызовите метод load:

Swift

private func loadAdManagerPictureInPictureAd() async {
  do {
    // Capture the PictureInPictureAd reference for later use.
    pipAd = try await PictureInPictureAd.load(
      with: adUnitID, request: AdManagerRequest())
    // Set the delegate to be notified of ad events.
    pipAd?.delegate = self
  } catch {
    print(
      "Picture-in-Picture ad failed to load: \(error.localizedDescription)")
  }
}

Замените adUnitID идентификатором своего рекламного блока.

Objective-C

- (void)loadAdManagerPictureInPictureAd {
  GAMRequest *request = [GAMRequest request];

  [GADPictureInPictureAd
       loadWithAdUnitID:kAdUnitID
                request:request
      completionHandler:^(GADPictureInPictureAd *_Nullable ad, NSError *_Nullable error) {
        if (error) {
          NSLog(@"Picture-in-Picture ad failed to load: %@", error);
          return;
        }
        // Capture the PictureInPictureAd reference for later use.
        self.pipAd = ad;
        // Set the delegate to be notified of ad events.
        self.pipAd.delegate = self;
      }];
}

Замените kAdUnitID идентификатором своего рекламного блока.

Покажите объявление

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

Swift

private func showPictureInPictureAd() {
  // Use the loaded PictureInPictureAd instance.
  guard let pipAd else {
    print("No ad to show.")
    return
  }
  let options = PictureInPictureAdOptions()
  // Uses the Google Mobile Ads SDK's default screen position.
  options.position = .default
  // Binds the ad lifecycle to the host screen.
  options.presentationScope = .screen

  pipAd.show(with: options)
}

Objective-C

- (void)showPictureInPictureAd {
  // Use the loaded PictureInPictureAd instance.
  if (!self.pipAd) {
    NSLog(@"No ad to show.");
    return;
  }
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Uses the Google Mobile Ads SDK's default screen position.
  options.position = GADPictureInPictureAdPositionDefault;
  // Binds the ad lifecycle to the host screen.
  options.presentationScope = GADPictureInPictureAdPresentationScopeScreen;

  [self.pipAd showWithOptions:options];
}

Задайте позицию

По умолчанию Google Mobile Ads SDK показывает объявление в режиме "картинка в картинке" в правом нижнем углу экрана, если оно показывается впервые, или в последней известной позиции, если оно уже показывалось. Чтобы настроить место показа объявления, укажите позицию при его показе. В следующем примере объявление размещается поверх контента в левом верхнем углу экрана:

Swift

private func createTopLeftPositionOptions() -> PictureInPictureAdOptions {
  let options = PictureInPictureAdOptions()
  // Sets the ad position to the top-left corner of the screen.
  options.position = .topLeft
  return options
}

Objective-C

- (GADPictureInPictureAdOptions *)createTopLeftPositionOptions {
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Sets the ad position to the top-left corner of the screen.
  options.position = GADPictureInPictureAdPositionTopLeft;
  return options;
}

Все доступные позиции перечислены в GADPictureInPictureAdPosition.

Как задать область действия презентации

По умолчанию Google Mobile Ads SDK привязывает объявление в режиме "картинка в картинке" к текущему экрану хоста. Google Mobile Ads SDK закрывает объявление, когда иерархия View основного экрана удаляется из памяти. Чтобы объявление оставалось видимым после удаления основного экрана из памяти, задайте область показа для приложения:

Swift

private func createApplicationScopedOptions() -> PictureInPictureAdOptions {
  let options = PictureInPictureAdOptions()
  // Keeps the ad visible beyond the host screen's lifecycle.
  options.presentationScope = .application
  return options
}

Objective-C

- (GADPictureInPictureAdOptions *)createApplicationScopedOptions {
  GADPictureInPictureAdOptions *options =
      [[GADPictureInPictureAdOptions alloc] init];
  // Keeps the ad visible beyond the host screen's lifecycle.
  options.presentationScope = GADPictureInPictureAdPresentationScopeApplication;
  return options;
}

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

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

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

Swift

func pictureInPictureAdDidShow(_ pictureInPictureAd: PictureInPictureAd) {
  print("Picture-in-Picture ad shown.")
}

func pictureInPictureAdDidHide(_ pictureInPictureAd: PictureInPictureAd) {
  print("Picture-in-Picture ad hidden.")
}

func pictureInPictureAdDidFailToShow(
  _ pictureInPictureAd: PictureInPictureAd, error: Error
) {
  print("Picture-in-Picture ad failed to show: \(error.localizedDescription)")
}

func pictureInPictureAdDidRecordImpression(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad recorded an impression.")
}

func pictureInPictureAdDidRecordClick(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad recorded a click.")
}

func pictureInPictureAdWillPresentScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad will present screen.")
}

func pictureInPictureAdWillDismissScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad will dismiss screen.")
}

func pictureInPictureAdDidDismissScreen(
  _ pictureInPictureAd: PictureInPictureAd
) {
  print("Picture-in-Picture ad dismissed screen.")
}

Objective-C

- (void)pictureInPictureAdDidShow:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad shown.");
}

- (void)pictureInPictureAdDidHide:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad hidden.");
}

- (void)pictureInPictureAdDidFailToShow:(GADPictureInPictureAd *)pictureInPictureAd
                              withError:(NSError *)error {
  NSLog(@"Picture-in-Picture ad failed to show: %@", error);
}

- (void)pictureInPictureAdDidRecordImpression:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad recorded an impression.");
}

- (void)pictureInPictureAdDidRecordClick:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad recorded a click.");
}

- (void)pictureInPictureAdWillPresentScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad will present screen.");
}

- (void)pictureInPictureAdWillDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad will dismiss screen.");
}

- (void)pictureInPictureAdDidDismissScreen:(GADPictureInPictureAd *)pictureInPictureAd {
  NSLog(@"Picture-in-Picture ad dismissed screen.");
}

Скрыть объявление

Чтобы убрать плавающее объявление с экрана, вызовите метод hide. Этот метод вызывает событие скрытия объявления:

Swift

private func hidePictureInPictureAd() {
  // Use the loaded PictureInPictureAd instance.
  guard let pipAd else {
    print("No ad to hide.")
    return
  }
  pipAd.hide()
}

Objective-C

- (void)hidePictureInPictureAd {
  // Use the loaded PictureInPictureAd instance.
  if (!self.pipAd) {
    NSLog(@"No ad to hide.");
    return;
  }
  [self.pipAd hide];
}

Очистить ресурсы объявлений

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

Swift

private func cleanUpPictureInPictureAd() {
  pipAd?.hide()
  pipAd = nil
}

Objective-C

- (void)cleanUpPictureInPictureAd {
  [self.pipAd hide];
  self.pipAd = nil;
}

Объявление должно быть видно на всех экранах

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

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