獎勵廣告

獎勵廣告是可讓使用者以換取應用程式內獎勵的方式與廣告互動。本指南說明如何將 Ad Manager的獎勵廣告整合至 iOS 應用程式。

必要條件

  • Google Mobile Ads SDK 8.0.0 以上版本。
  • 完成入門指南

一律使用測試廣告進行測試

建構及測試應用程式時,請務必使用測試廣告,而非正式版廣告。否則可能導致帳戶遭到停權。

如要載入測試廣告,最簡單的方法是使用 iOS 獎勵廣告專用的測試廣告單元 ID:

/6499/example/rewarded

我們已特別將每個請求設為傳回測試廣告;編寫程式碼、測試及偵錯時,您可以在自己的應用程式中自由使用這項工具。但請注意,發布應用程式前,請務必先將它換成自己的廣告單元 ID。

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

導入作業

整合插頁式獎勵廣告的主要步驟如下:

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

載入廣告

系統會使用 GADRewardedAd 類別上的靜態 loadWithAdUnitID:request:completionHandler: 方法載入廣告。載入方法需要您的廣告單元 ID、GAMRequest 物件,以及廣告載入成功或失敗時呼叫的完成處理常式。系統會在完成處理常式中,提供已載入的 GADRewardedAd 物件做為參數。以下範例說明如何在 ViewController 類別中載入 GADRewardedAd

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }
}

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/6499/example/rewarded"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
      }];
}

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

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

下列程式碼範例示範如何在請求廣告前,設定獎勵廣告物件的自訂資料。

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
  let options = GADServerSideVerificationOptions()
  options.customRewardString = "SAMPLE_CUSTOM_DATA_STRING"
  rewardedAd.serverSideVerificationOptions = options
} catch {
  print("Rewarded ad failed to load with error: \(error.localizedDescription)")
}

Objective-C

[GADRewardedAd
     loadWithAdUnitID:@"/6499/example/rewarded"
              request:[GAMRequest request];
    completionHandler:^(GADRewardedAd *ad, NSError *error) {
      if (error) {
        // Handle Error
        return;
      }
      self.rewardedAd = ad;
      GADServerSideVerificationOptions *options =
          [[GADServerSideVerificationOptions alloc] init];
      options.customRewardString = @"SAMPLE_CUSTOM_DATA_STRING";
      ad.serverSideVerificationOptions = options;
    }];

註冊回呼

如要接收顯示事件的通知,您必須導入 GADFullScreenContentDelegate 通訊協定,並將其指派給傳回廣告的 fullScreenContentDelegate 屬性。GADFullScreenContentDelegate 通訊協定會處理廣告成功或失敗及關閉時的回呼。以下程式碼顯示如何導入通訊協定,並將其指派給廣告:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/6499/example/rewarded", request: GAMRequest())
      rewardedAd?.fullScreenContentDelegate = self
    } catch {
      print("Rewarded ad failed to load with error: \(error.localizedDescription)")
    }
  }

  /// Tells the delegate that the ad failed to present full screen content.
  func ad(_ ad: GADFullScreenPresentingAd, didFailToPresentFullScreenContentWithError error: Error) {
    print("Ad did fail to present full screen content.")
  }

  /// Tells the delegate that the ad will present full screen content.
  func adWillPresentFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad will present full screen content.")
  }

  /// Tells the delegate that the ad dismissed full screen content.
  func adDidDismissFullScreenContent(_ ad: GADFullScreenPresentingAd) {
    print("Ad did dismiss full screen content.")
  }
}

Objective-C

@interface ViewController () <GADFullScreenContentDelegate>

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"ca-app-pub-3940256099942544/4806952744"
                request:request
      completionHandler:^(GADRewardedAd *ad, NSError *error) {
        if (error) {
          NSLog(@"Rewarded ad failed to load with error: %@", [error localizedDescription]);
          return;
        }
        self.rewardedAd = ad;
        NSLog(@"Rewarded ad loaded.");
        self.rewardedAd.fullScreenContentDelegate = self;
      }];
}

/// Tells the delegate that the ad failed to present full screen content.
- (void)ad:(nonnull id<GADFullScreenPresentingAd>)ad
    didFailToPresentFullScreenContentWithError:(nonnull NSError *)error {
    NSLog(@"Ad did fail to present full screen content.");
}

/// Tells the delegate that the ad will present full screen content.
- (void)adWillPresentFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad will present full screen content.");
}

/// Tells the delegate that the ad dismissed full screen content.
- (void)adDidDismissFullScreenContent:(nonnull id<GADFullScreenPresentingAd>)ad {
    NSLog(@"Ad did dismiss full screen content.");
}

GADRewardedAd 是一次性的物件。也就是說,獎勵廣告顯示後就無法再次顯示。最佳做法是在 GADFullScreenContentDelegateadDidDismissFullScreenContent: 方法中載入另一個獎勵廣告,以便在關閉上一個獎勵廣告後立即開始載入。

顯示廣告並處理獎勵事件

向使用者顯示獎勵廣告前,必須明確提供選項讓使用者觀看獎勵廣告內容,以換取獎勵。獎勵廣告一律必須為自選體驗。

放送廣告時,您必須提供 GADUserDidEarnRewardHandler 物件,以便處理使用者的獎勵。

下列程式碼是顯示獎勵廣告的最佳方法。

Swift

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

  // The UIViewController parameter is an optional.
  ad.present(fromRootViewController: nil) {
    let reward = ad.adReward
    print("Reward received with currency \(reward.amount), amount \(reward.amount.doubleValue)")
    // TODO: Reward the user.
  }
}

Objective-C

- (void)show {
  if (self.rewardedAd) {
    // The UIViewController parameter is nullable.
    [self.rewardedAd presentFromRootViewController:nil
                                  userDidEarnRewardHandler:^{
                                  GADAdReward *reward =
                                      self.rewardedAd.adReward;
                                  // TODO: Reward the user!
                                }];
  } else {
    NSLog(@"Ad wasn't ready");
  }
}

常見問題

我可以取得 GADRewardedAd的獎勵詳細資料嗎?
可以,如果您需要在 userDidEarnReward 回呼觸發前指定獎勵金額,GADRewardedAd 具備 adReward 屬性,可在廣告載入後確認獎勵金額。
初始化呼叫是否逾時?
10 秒後,即使中介服務聯播網尚未完成初始化,Google Mobile Ads SDK 也會叫用提供給 startWithCompletionHandler: 方法的 GADInitializationCompletionHandler
當我收到初始化回呼時,如果部分中介服務聯播網尚未準備就緒,該怎麼辦?

建議您在 GADInitializationCompletionHandler 內載入廣告。即使中介服務聯播網未準備就緒,Google Mobile Ads SDK 仍會要求該聯播網提供廣告。因此,如果中介服務聯播網在逾時後完成初始化,仍可在該工作階段中處理後續的廣告請求。

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

如何找出特定中介服務聯播網未準備就緒的原因?

GADAdapterStatus 物件的 description 屬性說明瞭轉接程式尚未準備好處理廣告請求的原因。

系統是否一律會在 adDidDismissFullScreenContent: 委派方法之前呼叫 userDidEarnRewardHandler 完成處理常式?

如果是 Google Ads,所有 userDidEarnRewardHandler 呼叫都會在 adDidDismissFullScreenContent: 之前進行。對於透過中介服務放送的廣告,第三方廣告聯播網 SDK 的實作方式會決定回呼順序。如果是提供獎勵資訊的單一委派方法,中介服務轉接程式會在 adDidDismissFullScreenContent: 之前叫用 userDidEarnRewardHandler

GitHub 上的範例

後續步驟

進一步瞭解使用者隱私