歡迎加入 Google 廣告與評估社群伺服器的官方 Ad Manager Discord 頻道，與成員一起討論產品並提供意見回饋。

獎勵廣告

選取平台： Android iOS Unity Flutter

獎勵廣告是一種可讓使用者選擇互動，以換取應用程式內獎勵的廣告形式。本指南說明如何在 iOS 應用程式中整合 Ad Manager 獎勵廣告。

前置作業

完整閱讀入門指南。

請務必使用測試廣告進行測試

建構及測試應用程式時，請務必使用測試廣告，而非實際的正式廣告；若未遵守此規定，可能導致帳戶遭到停權。

載入測試廣告最簡單的方法，是使用 iOS 獎勵廣告專用的測試廣告單元 ID：

/21775744923/example/rewarded

這個 ID 經過特別設定，每次請求都會傳回測試廣告。在編寫程式碼、測試及偵錯階段，您可以在應用程式中自由使用，但發布前記得要換成自己的廣告單元 ID。

如要進一步瞭解 Mobile Ads SDK 測試廣告的運作方式，請參閱「測試廣告」。

導入方式

整合獎勵廣告的主要步驟如下：

載入廣告
[選用] 驗證 SSV 回呼
註冊接收回呼
顯示廣告並處理獎勵事件

載入廣告

載入廣告時，請使用 GADRewardedAd 類別的 load(adUnitID:request) 方法。

Swift

func loadRewardedAd() async {
  do {
    rewardedAd = try await RewardedAd.load(
      // Replace this ad unit ID with your own ad unit ID.
      with: "/21775744923/example/rewarded", request: AdManagerRequest())
    rewardedAd?.fullScreenContentDelegate = self
  } catch {
    print("Rewarded ad failed to load with error: \(error.localizedDescription)")
  }
}ViewController.swift

SwiftUI

import GoogleMobileAds

class RewardedViewModel: NSObject, ObservableObject, FullScreenContentDelegate {
  @Published var coins = 0
  private var rewardedAd: RewardedAd?

  func loadAd() async {
    do {
      rewardedAd = try await RewardedAd.load(
        with: "ca-app-pub-3940256099942544/1712485313", request: Request())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Failed to load rewarded ad with error: \(error.localizedDescription)")
    }
  }RewardedViewModel.swift

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"/21775744923/example/rewarded"
              request:[GAMRequest request]
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
        return;
      }
      self.rewardedAd = ad;
      self.rewardedAd.fullScreenContentDelegate = self;
    }];ViewController.m

[選用] 驗證伺服器端驗證 (SSV) 回呼

在伺服器端驗證回呼中，如果應用程式需要加入額外資料，請使用獎勵廣告的自訂資料功能。在獎勵廣告物件上設定的任何字串值，都會傳遞至 SSV 回呼的 custom_data 查詢參數。如未設定任何自訂資料值，SSV 回呼就不會包含 custom_data 查詢參數值。

請參考下列程式碼範例，瞭解如何在請求廣告前，於獎勵廣告物件上設定自訂資料：

Swift

do {
  rewardedAd = try await RewardedAd.load(
    // Replace this ad unit ID with your own ad unit ID.
    with: "ca-app-pub-3940256099942544/1712485313", request: Request())
  let options = ServerSideVerificationOptions()
  options.customRewardText = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedAd?.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}RewardedAdSnippets.swift

Objective-C

// Replace this ad unit ID with your own ad unit ID.
[GADRewardedAd loadWithAdUnitID:@"ca-app-pub-3940256099942544/1712485313"
                        request:[GADRequest request]
              completionHandler:^(GADRewardedAd *ad, NSError *error) {
                if (error) {
                  NSLog(@"Rewarded ad failed to load with error: %@", error.localizedDescription);
                  return;
                }
                self.rewardedAd = ad;
                GADServerSideVerificationOptions *options =
                    [[GADServerSideVerificationOptions alloc] init];
                options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
                ad.serverSideVerificationOptions = options;
              }];RewardedAdSnippets.m

註冊接收回呼

為了接收廣告顯示事件的通知，必須將 GADFullScreenContentDelegate to the 指派給傳回廣告的 fullScreenContentDelegate` 屬性：

Swift

rewardedAd?.fullScreenContentDelegate = selfViewController.swift

SwiftUI

rewardedAd?.fullScreenContentDelegate = selfRewardedViewModel.swift

Objective-C

self.rewardedAd.fullScreenContentDelegate = self;ViewController.m

GADFullScreenContentDelegate 協定會處理廣告顯示成功、失敗及關閉時的回呼。以下是實作協定的程式碼：

Swift

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called.")
  // Clear the rewarded ad.
  rewardedAd = nil
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called with error: \(error.localizedDescription).")
}ViewController.swift

SwiftUI

func adDidRecordImpression(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidRecordClick(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func ad(
  _ ad: FullScreenPresentingAd,
  didFailToPresentFullScreenContentWithError error: Error
) {
  print("\(#function) called")
}

func adWillPresentFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adWillDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
}

func adDidDismissFullScreenContent(_ ad: FullScreenPresentingAd) {
  print("\(#function) called")
  // Clear the rewarded ad.
  rewardedAd = nil
}RewardedViewModel.swift

Objective-C

- (void)adDidRecordImpression:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidRecordClick:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillPresentFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adWillDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
}

- (void)adDidDismissFullScreenContent:(id<GADFullScreenPresentingAd>)ad {
  NSLog(@"%s called", __PRETTY_FUNCTION__);
  // Clear the rewarded ad.
  self.rewardedAd = nil;
}

- (void)ad:(id)ad didFailToPresentFullScreenContentWithError:(NSError *)error {
  NSLog(@"%s called with error: %@", __PRETTY_FUNCTION__, error.localizedDescription);
}ViewController.m

顯示廣告並處理獎勵事件

對使用者顯示獎勵廣告前，必須讓他們能明確選擇是否要觀看此類廣告來換取獎勵。獎勵廣告一定要使用者選擇觀看才會顯示。

顯示廣告時必須提供 GADUserDidEarnRewardHandler 物件，才能處理給使用者的獎勵。

請參考下列程式碼，瞭解如何以最佳方法顯示獎勵廣告。

Swift

rewardedAd.present(from: self) {
  let reward = rewardedAd.adReward
  print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")

  // TODO: Reward the user.
}ViewController.swift

SwiftUI

監聽檢視區塊中的 UI 事件，判斷何時顯示廣告。

var body: some View {
  VStack(spacing: 20) {
      Button("Watch video for additional 10 coins") {
        viewModel.showAd()
        showWatchVideoButton = false
      }RewardedContentView.swift

透過檢視區塊模型顯示獎勵廣告：

func showAd() {
  guard let rewardedAd = rewardedAd else {
    return print("Ad wasn't ready.")
  }

  rewardedAd.present(from: nil) {
    let reward = rewardedAd.adReward
    print("Reward amount: \(reward.amount)")
    self.addCoins(reward.amount.intValue)
  }
}RewardedViewModel.swift

Objective-C

[self.rewardedAd presentFromRootViewController:self
                      userDidEarnRewardHandler:^{
                        GADAdReward *reward = self.rewardedAd.adReward;
                        NSString *rewardMessage = [NSString
                            stringWithFormat:@"Reward received with currency %@ , amount %lf",
                                             reward.type, [reward.amount doubleValue]];
                        NSLog(@"%@", rewardMessage);

                        // TODO: Reward the user.
                      }];ViewController.m

常見問題

能否查看 GADRewardedAd 的獎勵詳細資料？

可以。如需在 userDidEarnReward 回呼觸發前得知獎勵數量，可以在廣告載入後檢查 GADRewardedAd 的 adReward 屬性。

初始化呼叫有逾時限制嗎？

初始化 10 秒後，即使有中介服務聯播網未完成初始化，Google Mobile Ads SDK 仍會叫用傳遞給 startWithCompletionHandler: 方法的 GADInitializationCompletionHandler。

收到初始化回呼時，如果部分中介服務聯播網尚未就緒，該怎麼辦？

建議在 GADInitializationCompletionHandler 中載入廣告。即使中介服務聯播網尚未就緒，Google Mobile Ads SDK 仍會請求廣告。中介服務聯播網若在逾時後完成初始化，仍能於該工作階段處理後續的廣告請求。

您可以在應用程式工作階段中持續呼叫 GADMobileAds.initializationStatus，輪詢所有轉接程式的初始化狀態。

如何找出特定中介服務聯播網尚未就緒的原因？

GADAdapterStatus 物件的 description 屬性會說明轉接程式無法處理廣告請求的原因。

userDidEarnRewardHandler 這個完成處理常式，一定會在 adDidDismissFullScreenContent: 委派方法之前獲得呼叫嗎？

對於 Google 廣告，userDidEarnRewardHandler 一定是在 adDidDismissFullScreenContent: 之前呼叫。若是透過中介服務放送的廣告，回呼順序則取決於第三方廣告聯播網 SDK 的導入方式。如果廣告聯播網 SDK 提供單一委派方法來包含獎勵資訊，中介服務轉接程式會先叫用 userDidEarnRewardHandler，再叫用 adDidDismissFullScreenContent:。

GitHub 範例程式碼

您可以依照偏好的程式語言，查看完整的獎勵廣告範例：

後續步驟

進一步瞭解使用者隱私。

獎勵廣告 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

前置作業

請務必使用測試廣告進行測試

導入方式

載入廣告

Swift

SwiftUI

Objective-C

[選用] 驗證伺服器端驗證 (SSV) 回呼

Swift

Objective-C

註冊接收回呼

Swift

SwiftUI

Objective-C

Swift

SwiftUI

Objective-C

顯示廣告並處理獎勵事件

Swift

SwiftUI

Objective-C

常見問題

GitHub 範例程式碼

後續步驟

獎勵廣告