Quảng cáo có tặng thưởng

Quảng cáo có tặng thưởng là những quảng cáo mà người dùng có thể chọn tương tác để đổi lấy phần thưởng trong ứng dụng. Hướng dẫn này sẽ cho bạn biết cách tích hợp quảng cáo có tặng thưởng từ Ad Manager vào ứng dụng iOS.

Điều kiện tiên quyết

• SDK quảng cáo trên thiết bị di động của Google phiên bản 8.0.0 trở lên.
• Xem hết hướng dẫn Bắt đầu sử dụng.

Luôn thử nghiệm bằng quảng cáo thử nghiệm

Khi tạo và thử nghiệm ứng dụng, hãy nhớ sử dụng quảng cáo thử nghiệm thay vì quảng cáo đang chạy trong thực tế. Nếu không làm như vậy, tài khoản của bạn có thể bị tạm ngưng.

Cách dễ nhất để tải quảng cáo thử nghiệm là sử dụng mã đơn vị quảng cáo thử nghiệm dành riêng cho quảng cáo có tặng thưởng trên iOS:

/21775744923/example/rewarded

Mã này được định cấu hình đặc biệt để trả về quảng cáo thử nghiệm cho mọi yêu cầu và bạn có thể sử dụng mã này trong ứng dụng của mình khi lập trình, chạy thử nghiệm và gỡ lỗi. Bạn chỉ cần nhớ thay thế mã này bằng mã đơn vị quảng cáo của mình trước khi xuất bản ứng dụng.

Để biết thêm thông tin về cách hoạt động của quảng cáo thử nghiệm của SDK quảng cáo trên thiết bị di động, hãy xem bài viết Quảng cáo thử nghiệm.

Triển khai

Sau đây là các bước chính để tích hợp quảng cáo có tặng thưởng:

• Tải quảng cáo
• [Không bắt buộc] Xác thực lệnh gọi lại của SSV
• Đăng ký lệnh gọi lại
• Hiển thị quảng cáo và xử lý sự kiện tặng thưởng

Tải quảng cáo

Bạn có thể tải một quảng cáo bằng cách sử dụng phương thức load(adUnitID:request) trên lớp GADRewardedAd.

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController {

  private var rewardedAd: GADRewardedAd?

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

SwiftUI

import GoogleMobileAds

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

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

Objective-C

@import GoogleMobileAds;
@import UIKit;

@interface ViewController ()

@property(nonatomic, strong) GADRewardedAd *rewardedAd;

@end

@implementation ViewController
- (void)loadRewardedAd {
  GAMRequest *request = [GAMRequest request];
  [GADRewardedAd
      loadWithAdUnitID:@"/21775744923/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.");
      }];
}

Mẹo: Bạn có thể sử dụng lệnh gọi tải quảng cáo để tạo bộ nhớ đệm của quảng cáo được tải trước trước khi bạn dự định hiển thị quảng cáo, nhờ đó quảng cáo có thể hiển thị mà không có độ trễ khi cần. Vì quảng cáo hết hạn sau một giờ, nên bạn nên xoá bộ nhớ đệm này và tải lại bằng quảng cáo mới mỗi giờ.

[Không bắt buộc] Xác thực lệnh gọi lại của tính năng xác minh phía máy chủ (SSV)

Những ứng dụng cần có thêm dữ liệu trong lệnh gọi lại của cơ chế xác minh phía máy chủ nên sử dụng tính năng dữ liệu tuỳ chỉnh của quảng cáo có tặng thưởng. Bất kỳ giá trị chuỗi nào được đặt cho đối tượng quảng cáo có tặng thưởng đều sẽ được truyền đến tham số truy vấn custom_data cho lệnh gọi lại của SSV. Nếu bạn không đặt giá trị dữ liệu tuỳ chỉnh, thì giá trị tham số truy vấn custom_data sẽ không hiển thị trong lệnh gọi lại của SSV.

Mã mẫu sau đây minh hoạ cách đặt dữ liệu tuỳ chỉnh cho đối tượng quảng cáo có tặng thưởng trước khi yêu cầu quảng cáo.

Swift

do {
  rewardedAd = try await GADRewardedAd.load(
    withAdUnitID: "/21775744923/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:@"/21775744923/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;
    }];

Lưu ý quan trọng: Kể từ phiên bản SDK 7.50.0, bạn có thể đặt chuỗi phần thưởng tuỳ chỉnh vào bất cứ thời điểm nào.

Lưu ý quan trọng: Chuỗi phần thưởng tuỳ chỉnh là tỷ lệ phần trăm lệnh gọi lại bị thoát và có thể cần được giải mã khi được phân tích cú pháp từ lệnh gọi lại của SSV.

Đăng ký lệnh gọi lại

Để nhận thông báo cho các sự kiện trình bày, bạn phải triển khai giao thức GADFullScreenContentDelegate và chỉ định giao thức đó cho thuộc tính fullScreenContentDelegate của quảng cáo được trả về. Giao thức GADFullScreenContentDelegate xử lý các lệnh gọi lại khi quảng cáo hiển thị thành công hoặc không thành công và khi quảng cáo bị loại bỏ. Đoạn mã sau đây cho biết cách triển khai giao thức và chỉ định giao thức đó cho quảng cáo:

Swift

import GoogleMobileAds
import UIKit

class ViewController: UIViewController, GADFullScreenContentDelegate {

  private var rewardedAd: GADRewardedAd?

  func loadRewardedAd() async {
    do {
      rewardedAd = try await GADRewardedAd.load(
        withAdUnitID: "/21775744923/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.")
  }
}

SwiftUI

Chỉ định thuộc tính fullScreenContentDelegate cho quảng cáo được trả về:

rewardedAd?.fullScreenContentDelegate = self
RewardedViewModel.swift

Triển khai giao thức:

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

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

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

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

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

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

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 là đối tượng dùng một lần. Điều này có nghĩa là sau khi quảng cáo có tặng thưởng xuất hiện, quảng cáo đó sẽ không thể hiển thị lại. Phương pháp hay nhất là tải một quảng cáo có tặng thưởng khác trong phương thức adDidDismissFullScreenContent: trên GADFullScreenContentDelegate để quảng cáo có tặng thưởng tiếp theo bắt đầu tải ngay khi quảng cáo trước đó bị đóng.

Hiển thị quảng cáo và xử lý sự kiện tặng thưởng

Trước khi hiển thị quảng cáo có tặng thưởng cho người dùng, bạn phải cho người dùng biết rõ về việc lựa chọn xem nội dung quảng cáo có tặng thưởng để đổi lấy phần thưởng. Người dùng phải luôn có thể chọn xem hoặc không xem quảng cáo có tặng thưởng.

Khi hiển thị quảng cáo, bạn phải cung cấp một đối tượng GADUserDidEarnRewardHandler để xử lý phần thưởng cho người dùng.

Bạn nên sử dụng đoạn mã sau đây để hiển thị quảng cáo có tặng thưởng.

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

SwiftUI

Theo dõi các sự kiện trên giao diện người dùng trong thành phần hiển thị để xác định thời điểm hiển thị quảng cáo.

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

Trình bày quảng cáo có tặng thưởng từ mô hình thành phần hiển thị:

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

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

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

Câu hỏi thường gặp

Tôi có thể nhận thông tin chi tiết về phần thưởng cho GADRewardedAd không?

Có, nếu bạn cần biết số tiền thưởng trước khi kích hoạt lệnh gọi lại userDidEarnReward, GADRewardedAd có thuộc tính adReward để bạn có thể kiểm tra nhằm xác minh số tiền thưởng sau khi quảng cáo đã tải.

Lệnh gọi khởi động có thời gian chờ không?

Sau 10 giây, SDK quảng cáo trên thiết bị di động của Google sẽ gọi GADInitializationCompletionHandler đã cung cấp cho phương thức startWithCompletionHandler:, ngay cả khi mạng dàn xếp chưa hoàn tất quy trình khởi chạy.

Điều gì xảy ra nếu một số mạng dàn xếp chưa sẵn sàng hoạt động khi tôi nhận được lệnh gọi lại dùng để khởi động?

Bạn nên tải quảng cáo bên trong GADInitializationCompletionHandler. Ngay cả khi mạng dàn xếp chưa sẵn sàng hoạt động, SDK Quảng cáo của Google trên thiết bị di động vẫn yêu cầu mạng đó cung cấp một quảng cáo. Vì vậy, nếu quá trình khởi động kết thúc sau khi hết thời gian chờ, thì mạng dàn xếp vẫn có thể thực hiện các yêu cầu quảng cáo tiếp theo trong phiên đó.

Bạn có thể tiếp tục thăm dò trạng thái khởi chạy của tất cả các bộ chuyển đổi trong suốt phiên hoạt động ứng dụng của mình bằng cách gọi GADMobileAds.initializationStatus.

Làm cách nào để biết lý do khiến một mạng dàn xếp cụ thể chưa sẵn sàng hoạt động?

Thuộc tính description của đối tượng GADAdapterStatus cho biết lý do khiến bộ chuyển đổi chưa sẵn sàng phân phát các yêu cầu quảng cáo.

Trình xử lý hoàn thành userDidEarnRewardHandler có luôn được gọi trước phương thức uỷ quyền adDidDismissFullScreenContent: không?

Đối với quảng cáo của Google, tất cả lệnh gọi userDidEarnRewardHandler đều xảy ra trước adDidDismissFullScreenContent:. Đối với những quảng cáo được phân phát thông qua tính năng dàn xếp, hoạt động triển khai SDK của mạng quảng cáo bên thứ ba sẽ xác định thứ tự lệnh gọi lại. Đối với các SDK của mạng quảng cáo cung cấp một phương thức uỷ quyền có thông tin về phần thưởng, bộ chuyển đổi dàn xếp sẽ gọi userDidEarnRewardHandler trước adDidDismissFullScreenContent:.

Ví dụ trên GitHub

Xem ví dụ đầy đủ về quảng cáo có tặng thưởng bằng ngôn ngữ bạn muốn:

• Swift
• SwiftUI
• Objective-C

Các bước tiếp theo

Tìm hiểu thêm về quyền riêng tư của người dùng.