Triển khai Bộ chuyển đổi quảng cáo có tặng thưởng

Lưu ý quan trọng: Khi sử dụng SDK quảng cáo trên thiết bị di động của Google cùng với Dịch vụ dàn xếp, bạn phải tuân thủ Điều khoản dịch vụ dàn xếp.

Bộ chuyển đổi dàn xếp sẽ nhận các thông báo và yêu cầu từ SDK quảng cáo trên thiết bị di động của Google, đồng thời giao tiếp với SDK mạng của bên thứ ba để đáp ứng các yêu cầu đó.

Hướng dẫn này dành cho các mạng quảng cáo đang tìm cách tạo một bộ chuyển đổi dàn xếp quảng cáo có tặng thưởng cho tính năng Dàn xếp quảng cáo trên thiết bị di động của Google. Chúng tôi sử dụng SDK mẫu trong các đoạn mã dưới đây cho mục đích minh hoạ. Bạn có thể tìm thấy hoạt động triển khai đầy đủ của một bộ chuyển đổi được tạo cho SDK mẫu này trong dự án Dàn xếpiOS của chúng tôi. Hướng dẫn này giải thích cách tạo bộ chuyển đổi.

Xác định tên lớp bộ chuyển đổi và tham số máy chủ

Những mạng quảng cáo được dàn xếp thông qua nền tảng dàn xếp AdMob thường yêu cầu một hoặc nhiều giá trị nhận dạng để nhận dạng một nhà xuất bản. Các giá trị nhận dạng này được biểu thị dưới dạng thông số máy chủ và được xác định khi định cấu hình mạng quảng cáo bên thứ ba cho hoạt động dàn xếp trong giao diện người dùng AdMob.

Trước khi phát triển bộ chuyển đổi dàn xếp, bạn phải cung cấp cho Google tên lớp của bộ chuyển đổi đó và các thông số bắt buộc khác để có quyền truy cập vào mạng quảng cáo của bạn.

Tuân thủ giao thức GADMediationAdapter

Bước đầu tiên là để lớp bộ chuyển đổi của bạn triển khai giao thức GADMediationAdapter:

#import <Foundation/Foundation.h>
#import <GoogleMobileAds/GoogleMobileAds.h>
#import <SampleAdSDK/SampleAdSDK.h>

@interface GADMediationAdapterSampleAdNetwork : NSObject <GADMediationAdapter>
@end

Thay đổi này đảm bảo rằng lớp của bạn triển khai một số phương thức được thảo luận dưới đây.

Báo cáo lớp bổ sung

Nếu mạng bên thứ ba muốn cho phép nhà xuất bản truyền các thông số bổ sung không bắt buộc cho một yêu cầu quảng cáo, thì lớp extras phải được trả về từ phương thức networkExtrasClass. Trả về Nil nếu bên thứ ba không hỗ trợ lớp bổ sung do nhà xuất bản cung cấp.

#import <GoogleMobileAds/GoogleMobileAds.h>

@interface SampleExtras : NSObject<GADAdNetworkExtras>

/// Use this to indicate if debug mode is on for logging.
@property(nonatomic) BOOL debugLogging;

/// Use this to indicate whether to mute audio for video ads.
@property(nonatomic) BOOL muteAudio;

@end

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
  return [SampleExtras class];
}
...
@end

Số phiên bản báo cáo

Bộ chuyển đổi đó phải báo cáo cho SDK quảng cáo trên thiết bị di động của Google cả phiên bản của chính bộ chuyển đổi đó và phiên bản SDK của bên thứ ba. Các phiên bản được báo cáo bằng GADVersionNumber.

Bộ chuyển đổi nguồn mở và được tạo phiên bản của Google sử dụng lược đồ phiên bản bộ chuyển đổi 4 chữ số, nhưng GADVersionNumber chỉ cho phép 3 chữ số. Để giải quyết vấn đề này, bạn nên kết hợp 2 chữ số cuối vào phiên bản bản vá, như thể hiện dưới đây:

#import "GADMediationAdapterSampleAdNetwork.h"

@implementation GADMediationAdapterSampleAdNetwork
...
+ (GADVersionNumber)adSDKVersion {
  NSString *versionString = SampleSDKVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 3) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    version.patchVersion = [versionComponents[2] integerValue];
  }
  return version;
}

+ (GADVersionNumber)version {
  NSString *versionString = SampleAdapterVersion;
  NSArray *versionComponents = [versionString componentsSeparatedByString:@"."];

  GADVersionNumber version = {0};
  if (versionComponents.count >= 4) {
    version.majorVersion = [versionComponents[0] integerValue];
    version.minorVersion = [versionComponents[1] integerValue];
    // Adapter versions have 2 patch versions. Multiply the first patch by 100.
    version.patchVersion =
        [versionComponents[2] integerValue] * 100 + [versionComponents[3] integerValue];
  }
  return version;
}
...
@end

Khởi chạy bộ chuyển đổi

Khi một ứng dụng khởi chạy SDK quảng cáo trên thiết bị di động của Google, setUpWithConfiguration:completionHandler: sẽ được gọi trên tất cả các bộ chuyển đổi được định cấu hình cho ứng dụng đó trong giao diện người dùng AdMob.

Đối số GADMediationServerConfiguration cung cấp thông tin về tất cả các vị trí đã định cấu hình cho ứng dụng trong giao diện người dùng AdMob. Hãy sử dụng thông tin này để khởi chạy SDK mạng quảng cáo của bạn. Sau khi SDK mạng quảng cáo được khởi động, hãy gọi đối số GADMediationAdapterSetUpCompletionBlock. Khối này cho phép bạn báo cáo việc khởi chạy thành công hoặc thất bại cho SDK quảng cáo trên thiết bị di động của Google bằng cách gọi trình xử lý hoàn thành với nil hoặc đối tượng NSError.

#import "SampleAdapter.h"

@implementation SampleAdapter
...
+ (void)setUpWithConfiguration:(GADMediationServerConfiguration *)configuration
             completionHandler:(GADMediationAdapterSetUpCompletionBlock)completionHandler {
  // Since the Sample SDK doesn't need to be initialized, the completion
  //handler is called directly here.
  completionHandler(nil);
}
...
@end

Yêu cầu quảng cáo có tặng thưởng

Khi một ứng dụng tải quảng cáo có tặng thưởng bằng SDK quảng cáo trên thiết bị di động của Google, loadRewardedAdForAdConfiguration:completionHandler: sẽ được gọi trên bộ chuyển đổi nếu mạng quảng cáo của bạn đạt đến trong quy trình dàn xếp kiểu thác nước.

GADRewardedLoadCompletionHandler cho phép bạn báo cáo một lượt tải quảng cáo thành công cho SDK quảng cáo trên thiết bị di động của Google bằng cách cung cấp một mục tham chiếu đến một đối tượng tuân thủ giao thức GADMediationRewardedAd, hoặc một lượt tải quảng cáo không thành công bằng cách cung cấp tệp đối chiếu nil và đối tượng NSError. Lệnh gọi trình xử lý tải hoàn thành sẽ trả về một GADMediationRewardedAdEventDelegate mà bộ chuyển đổi sẽ giữ trong vòng đời của quảng cáo để thông báo cho SDK quảng cáo trên thiết bị di động của Google về mọi sự kiện tiếp theo.

#import "SampleAdapter.h"

@interface SampleAdapter () <GADMediationRewardedAd> {
  /// Rewarded ads from Sample SDK.
  SampleRewardedAd *_rewardedAd;

  /// Handles any callback when the sample rewarded ad finishes loading.
  GADMediationRewardedLoadCompletionHandler _loadCompletionHandler;

  /// Delegate for receiving rewarded ad notifications.
  __weak id<GADMediationRewardedAdEventDelegate> _rewardedAdDelegate;
}
@end

@implementation SampleAdapter
...
- (void)loadRewardedAdForAdConfiguration:(GADMediationRewardedAdConfiguration *)adConfiguration
                       completionHandler:
                           (GADMediationRewardedLoadCompletionHandler)completionHandler {
  _loadCompletionHandler = completionHandler;

  NSString *adUnit = adConfiguration.credentials.settings[SampleSDKAdUnitIDKey];
  SampleExtras *extras = adConfiguration.extras;

  _rewardedAd = [[SampleRewardedAd alloc] initWithAdUnitID:adUnit];
  _rewardedAd.enableDebugLogging = extras.enableDebugLogging;

  /// Check the extras to see if the request should be customized.
  SampleAdRequest *request = [[SampleAdRequest alloc] init];
  request.mute = extras.muteAudio;

  /// Set the delegate on the rewarded ad to listen for callbacks from the Sample SDK.
  _rewardedAd.delegate = self;
  [_rewardedAd fetchAd:request];
}
...
@end

Chuyển tiếp sự kiện tải quảng cáo

Bộ chuyển đổi có trách nhiệm theo dõi các lệnh gọi lại SDK của bên thứ ba và liên kết các lệnh gọi lại đó với lệnh gọi lại SDK quảng cáo trên thiết bị di động của Google thích hợp.

Báo cáo sự thành công hoặc thất bại của các sự kiện tải quảng cáo bên thứ ba bằng cách gọi loadCompletionHandler với một quảng cáo hoặc lỗi. Nếu trình xử lý hoàn thành được gọi cùng với một quảng cáo và không có lỗi, thì hệ thống sẽ trả về một đối tượng uỷ quyền sự kiện quảng cáo. Hãy tiếp tục tham chiếu đến đại biểu này để bộ chuyển đổi của bạn có thể chuyển tiếp các sự kiện trình bày sau.

- (void)rewardedAdDidReceiveAd:(nonnull SampleRewardedAd *)rewardedAd {
  _rewardedAdDelegate = _loadCompletionHandler(self, nil);
}

- (void)rewardedAdDidFailToLoadWithError:(SampleErrorCode)errorCode {
  _loadCompletionHandler(nil, [NSError errorWithDomain:kAdapterErrorDomain
                                                  code:GADErrorNoFill
                                              userInfo:nil]);
}

Hiển thị quảng cáo

Khi ứng dụng yêu cầu SDK quảng cáo trên thiết bị di động của Google hiển thị quảng cáo có tặng thưởng, SDK sẽ gọi phương thức presentFromViewController: trên bản sao của GADMediationRewardedAd được cung cấp trong lệnh gọi đến trình xử lý tải hoàn thành. Tại đây, bạn sẽ hiển thị quảng cáo có tặng thưởng:

- (void)presentFromViewController:(nonnull UIViewController *)viewController {
  if (!_rewardedAd.isReady) {
    NSError *error =
        [NSError errorWithDomain:kAdapterErrorDomain
                            code:0
                        userInfo:@{NSLocalizedDescriptionKey : @"Unable to display ad."}];
    [_rewardedAdDelegate didFailToPresentWithError:error];
    return;
  }
  [_rewardedAd presentFromRootViewController:viewController];
}

Báo cáo sự kiện quảng cáo cho SDK quảng cáo trên thiết bị di động

Sau khi hiển thị quảng cáo, bộ chuyển đổi sẽ báo cáo các sự kiện trong vòng đời hiển thị quảng cáo bằng cách sử dụng cùng một đại biểu sự kiện quảng cáo được trả về tại thời điểm tải quảng cáo thành công.

- (void)rewardedAdDidPresent:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willPresentFullScreenView];
  [_rewardedAdDelegate didStartVideo];
  [_rewardedAdDelegate reportImpression];
}

- (void)rewardedAdDidDismiss:(nonnull SampleRewardedAd *)rewardedAd {
  [_rewardedAdDelegate willDismissFullScreenView];
  [_rewardedAdDelegate didEndVideo];
  [_rewardedAdDelegate didDismissFullScreenView];
}
- (void)rewardedAd:(nonnull SampleRewardedAd *)rewardedAd userDidEarnReward:(NSUInteger)reward {
  GADAdReward *aReward =
      [[GADAdReward alloc] initWithRewardType:@"GADMediationAdapterSampleAdNetwork"
                                 rewardAmount:[NSDecimalNumber numberWithUnsignedInt:reward]];
  [_rewardedAdDelegate didRewardUserWithReward:aReward];
}

Dưới đây là thông tin chi tiết về các sự kiện quảng cáo cần được báo cáo cho SDK quảng cáo trên thiết bị di động của Google:

Sự kiện quảng cáo	Nội dung mô tả
willPresentFullScreenView	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng quảng cáo sẽ hiển thị.
didStartVideo	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng quảng cáo có tặng thưởng đã bắt đầu phát.
reportImpression	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng đã có một lượt hiển thị trên quảng cáo.
didEndVideo	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng quảng cáo có tặng thưởng đã phát xong.
didRewardUserWithReward	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng người dùng đã được tặng thưởng.
reportClick	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng đã có lượt nhấp vào quảng cáo.
willDismissFullScreenView	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng quảng cáo sẽ bị đóng.
didDismissFullScreenView	Thông báo cho SDK quảng cáo trên thiết bị di động của Google rằng quảng cáo đã bị đóng.