導入子母畫面廣告 (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 版)