植入画中画广告（Beta 版）

请选择平台： Android iOS

画中画

画中画 (PiP) 广告会在浮动窗口中展示，该窗口会始终显示在屏幕内容（例如文章、信息流或游戏内容）之上。这种格式让用户可以在广告保持可见的同时与您的应用互动。如需展示不占据整个屏幕的广告，请选择此格式。详细了解画中画广告。

本指南介绍了如何使用 Google Mobile Ads SDK 在应用中请求和展示画中画广告。

准备工作

在继续操作之前，请先完成以下事项：

设置 Google Mobile Ads SDK。
安装 Google Mobile Ads SDK 13.10.0 版或更高版本。
启用测试广告，并使用以下测试广告单元 ID： ca-app-pub-3940256099942544/8810945611

加载广告

如需加载 GADPictureInPictureAd 对象，请创建一个广告请求并调用 load 方法：

Swift

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

请将 adUnitID 替换为您的广告单元 ID。

Objective-C

- (void)loadPictureInPictureAd {
  GADRequest *request = [GADRequest 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 替换为您的广告单元 ID。

展示广告

如需在屏幕上展示画中画广告，请配置画中画选项并调用 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 会在宿主屏幕的视图层次结构不再位于内存中时关闭广告。如需在宿主屏幕从内存中移除后仍保持广告可见，请将展示范围设置为应用：

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

让广告在各种屏幕上都清晰可见

将展示范围设置为应用后，即使应用从内存中移除托管屏幕，画中画广告仍会保持可见。当用户离开宿主屏幕时，为了与广告互动或关闭广告，您的应用必须保留对画中画广告的访问权限。我们建议将广告保存在应用级单例或共享状态管理器中，而不是保存在单个屏幕的实例变量中。

植入画中画广告（Beta 版） 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

加载广告

Swift

Objective-C

展示广告

Swift

Objective-C

设置位置

Swift

Objective-C

设置展示范围

Swift

Objective-C

设置广告事件回调

Swift

Objective-C

隐藏广告

Swift

Objective-C

清理广告资源

Swift

Objective-C

让广告在各种屏幕上都清晰可见

植入画中画广告（Beta 版）