Tạo bộ chuyển đổi tín hiệu an toàn

Tín hiệu bảo mật là dữ liệu được mã hoá mà thiết bị khách thu thập và chia sẻ với một số bên đặt giá thầu. Trang này hướng dẫn bạn thu thập và gửi tín hiệu an toàn đến Google Ad Manager bằng cách sử dụng SDK Quảng cáo trên phương tiện truyền thông tương tác (IMA).

Trước khi bắt đầu

Trước khi tiếp tục, hãy đảm bảo bạn có SDK IMA cho iOS phiên bản 3.18.5 trở lên.

Tạo giao diện bộ chuyển đổi tín hiệu bảo mật

Để thu thập và cung cấp tín hiệu an toàn, hãy tạo các lớp triển khai giao diện:

Objective-C

  • MySecureSignalsAdapter.h:
#import <Foundation/Foundation.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
/** An example implementation of Secure Signals adapter. */
@interface MySecureSignalsAdapter : NSObject <IMASecureSignalsAdapter>
@end
  • MySecureSignalsAdapter.m:
@implementation MySecureSignalsAdapter

  /**
* Default constructor with no arguments for IMA SDK to instantiate this class.
*/
- (instancetype)init {
  self = [super init];

  return self;
}
@end

Swift 

import Foundation
import GoogleInteractiveMediaAds

/** An example implementation of Secure Signals adapter. */
@objc(MySecureSignalsAdapter)
public class MySecureSignalsAdapter: IMASecureSignalsAdapter {
  /**
  * Default constructor with no arguments for IMA SDK to instantiate this class.
  */
  override init() {
    super.init()
  }
}

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

SDK IMA khởi chạy mỗi bộ chuyển đổi một lần bằng cách gọi phương thức khởi chạy của bộ chuyển đổi. Triển khai phương thức này để bắt đầu mọi phần phụ thuộc mã hoá, thiết lập bộ nhớ đệm hoặc tính toán trước mọi tín hiệu vẫn giữ nguyên trong tất cả các lệnh gọi thu thập tín hiệu.

Ví dụ sau đây sẽ khởi chạy trình chuyển đổi:

Objective-C 

...
@interface MySecureSignalsAdapter
@property(nonatomic) NSError *initError;
@end
...
/**
* Initialize your SDK and any dependencies.
* IMA SDK calls this function exactly once before signal collection.
*/
- (instancetype)init {
  self = [super init];
  @try {
    // Initialize your SDK and any dependencies.
    ...
  }
  @catch(NSException *exception) {
    // Build NSError to be passed by Signal Collector.
    _initError = ...;
  }
  return self;
}
...

Swift 

...
@objc(MySecureSignalsAdapter)
public class MySecureSignalsAdapter: IMASecureSignalsAdapter {
...
  private var initError

  override init() {
    super.init()

    do {
      // Initialize your SDK and any dependencies.
      ...
    } catch {
      // Build NSError to be passed by Signal Collector.
      self.initError = ...;
    }
  }
}

Thu thập tín hiệu

Trước khi một yêu cầu quảng cáo bắt đầu, SDK IMA sẽ gọi một phương thức thu thập tín hiệu một cách không đồng bộ. Các phương thức thu thập tín hiệu này chứa một hàm gọi lại để truyền các tín hiệu đã mã hoá hoặc báo cáo lỗi.

Các ví dụ sau đây thu thập tín hiệu an toàn thông qua hàm gọi lại:

Objective-C 

...
/**
* Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
* IMA SDK calls this function before each ad request.
*
* @param completion A callback function to pass signal collection results to IMA SDK.
*/
- (void)collectSignalsWithCompletion:(IMASignalCompletionHandler)completion {
  // Output any initialization errors
  if (self.initError) {
    completion(nil, self.initError);
    return;
  }
  @try {
    // Collect and encrypt the signals.
    NSString *signals = ...
    // Pass the encrypted signals to IMA SDK.
    completion(signals, nil);
  }
  @catch(NSException *exception) {
    NSError *collectSignalError = ...;
    // Pass signal collection failures to IMA SDK.
    completion(nil, collectSignalError);
  }
}
...

Swift 

...
  /**
  * Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
  * IMA SDK calls this function before each ad request.
  *
  * @param completion A callback function to pass signal collection results to IMA SDK.
  */
  public func collectSignals(completion: @escaping IMASignalCompletionHandler) {
    if (self.initError) {
      completion(nil, self.initError)
      return
    }

    do {
      // Collect and encrypt the signals.
      var signals = ...
      // Pass the encrypted signals to IMA SDK.
      completion(signals, nil)
    } catch {
      NSError collectSignalError = ...
      // Pass signal collection failures to IMA SDK.
      completion(nil, collectSignalError)
    }
  }
...

Báo cáo lỗi

Để giao tiếp với những người dùng sử dụng lớp bộ chuyển đổi, hãy báo cáo tất cả lỗi trong quá trình thu thập tín hiệu và chuyển các lỗi đó đến lệnh gọi lại của trình thu thập tín hiệu. Quy trình này khắc phục các sự cố xảy ra trong quá trình tích hợp bộ chuyển đổi với các ứng dụng.

Sau đây là các lỗi có thể xuất hiện:

  • Không tìm thấy SDK hoặc phần phụ thuộc trong ứng dụng.
  • SDK của bạn hoặc một phần phụ thuộc không có quyền cần thiết hoặc không có sự đồng ý của người dùng để hoạt động.

Chỉ định phiên bản bộ chuyển đổi

Trong quy trình làm việc, hãy đảm bảo bạn chỉ định phiên bản của bộ chuyển đổi. SDK IMA bao gồm phiên bản bộ chuyển đổi của bạn trong mỗi yêu cầu quảng cáo và truyền các yêu cầu đó cùng với các tín hiệu bảo mật trong yêu cầu giá thầu.

Trong yêu cầu giá thầu, dựa trên phiên bản bộ chuyển đổi, bạn có thể xác định thông tin chi tiết về việc mã hoá, mã hoá và định dạng mà bộ chuyển đổi sử dụng để tạo tín hiệu bảo mật.

Ví dụ sau đây chỉ định phiên bản bộ chuyển đổi:

Objective-C 

...
/**
* Specifies this adapter's version.
*/
static NSInteger const VersionMajor = 1;
static NSInteger const VersionMinor = 0;
static NSInteger const VersionPatch = 1;
...
/**
* @return The version of this adapter.
*         IMA SDK calls this function before each ad request.
*/
+ (IMAVersion *)adapterVersion {
  // The version of the SecureSignals Adapter.
  IMAVersion *adapterVersion = [[IMAVersion alloc] init];
  adapterVersion.majorVersion = VersionMajor;
  adapterVersion.minorVersion = VersionMinor;
  adapterVersion.patchVersion = VersionPatch;
  return adapterVersion;
}
...

Swift 

...
  /**
  * Specifies this adapter's version.
  */
  static let VersionMajor = 1;
  static let VersionMinor = 0;
  static let VersionPatch = 1;
...
  /**
  * @return The version of this adapter.
  *         IMA SDK calls this function before each ad request.
  */
  public static func adapterVersion() -> IMAVersion {
    let adapterVersion = IMAVersion()
    adapterVersion.majorVersion = self.VersionMajor
    adapterVersion.minorVersion = self.VersionMinor
    adapterVersion.patchVersion = self.VersionPatch
    return adapterVersion
  }
...

Trả về phiên bản thời gian chạy SDK

Bạn có thể thiết kế bộ chuyển đổi để hoạt động với nhiều phiên bản SDK. Để bộ chuyển đổi hoạt động với nhiều phiên bản, hãy đảm bảo bạn trả về phiên bản thời gian chạy của SDK. Trong mỗi yêu cầu quảng cáo, SDK IMA bao gồm phiên bản thời gian chạy với phiên bản bộ chuyển đổi.

Các ví dụ sau đây yêu cầu và trả về phiên bản thời gian chạy SDK:

Objective-C 

...
/**
* @return The version of your SDK that this adapter is depending on.
*         IMA SDK calls this function before each ad request.
*/
+ (IMAVersion *)adSDKVersion {
  // Request the version from your SDK and convert to an IMAVersion.
  int mySDKVersion[3] = ...

  IMAVersion *adSDKVersion = [[IMAVersion alloc] init];
  adSDKVersion.majorVersion = mySDKVersion[0];
  adSDKVersion.minorVersion = mySDKVersion[1];
  adSDKVersion.patchVersion = mySDKVersion[2];

  return adSDKVersion;
}
...

Swift 

...
  /**
  * @return The version of your SDK that this adapter is depending on.
  *         IMA SDK calls this function before each ad request.
  */
public static func adSDKVersion() -> IMAVersion {
    // Request the version from your SDK and convert to an IMAVersion.
    let mySDKVersion = ...

    let adSDKVersion = IMAVersion()
    adSDKVersion.majorVersion = mySDKVersion[0]
    adSDKVersion.minorVersion = mySDKVersion[1]
    adSDKVersion.patchVersion = mySDKVersion[2]
    return adSDKVersion
  }
...

Đăng ký bộ chuyển đổi với Google

Để Google cho phép bộ chuyển đổi thu thập tín hiệu, bạn phải đăng ký tên lớp iOS với Google. SDK IMA chỉ khởi chạy các bộ chuyển đổi mà bạn đăng ký với Google.

Xác thực bộ chuyển đổi

Để xác thực bộ chuyển đổi, hãy hoàn thành các phần sau:

Định cấu hình ứng dụng kiểm thử

Trước khi xác thực bộ chuyển đổi, hãy định cấu hình ứng dụng kiểm thử. Hoàn tất các bước sau:

  1. Thêm SDK IMA vào tệp pod:

    source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '10'
target "BasicExample" do
  pod 'GoogleAds-IMA-iOS-SDK', '~> 3.17.0'
end

  2. Cài đặt SDK IMA bằng CocoaPods. Để biết hướng dẫn cài đặt SDK IMA thông qua CocoaPods, hãy xem phần Bắt đầu.

  3. Trong dự án XCode, hãy thêm trình chuyển đổi, SDK và mọi phần phụ thuộc bản dựng còn lại mà bạn đã thêm.

Xác minh tín hiệu

Để xác minh độ dài của tín hiệu an toàn, giá trị được mã hoá, phiên bản bộ chuyển đổi và phiên bản SDK của bạn, hãy liên hệ với bộ phận hỗ trợ để chia sẻ nhật ký lưu lượng truy cập đã ghi lại.

Xem xét các ví dụ đầy đủ

Phần này cung cấp ví dụ hoàn chỉnh về tất cả các bước và có sẵn để bạn tham khảo.

Objective-C

  • MySecureSignalsAdapter.h:
#import <Foundation/Foundation.h>
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>

/** An example implementation of Secure Signals adapter. */
@interface MySecureSignalsAdapter : NSObject <IMASecureSignalsAdapter>
@end
  • MySecureSignalsAdapter.m:
#import "path/to/MyExampleSecureSignalsAdapter.h"

@interface MySecureSignalsAdapter
@property(nonatomic) NSError *initError;
@end

static NSInteger const VersionMajor = 1;
static NSInteger const VersionMinor = 0;
static NSInteger const VersionPatch = 1;

@implementation MySecureSignalsAdapter
/**
* Initialize your SDK and any dependencies.
* IMA SDK calls this function exactly once before signal collection.
*/
- (instancetype)init {
  self = [super init];
  @try {
    // Initialize your SDK and any dependencies.
    ...
  }
  @catch(NSException *exception) {
    // Build NSError to be passed by Signal Collector.
    _initError = ...;
  }
  return self;
}
/**
* Invokes your SDK to collect, encrypt and pass the signal collection results to IMA SDK.
* IMA SDK calls this function before each ad request.
*
* @param completion A callback function to pass signal collection results to IMA SDK.
*/
- (void)collectSignalsWithCompletion:(IMASignalCompletionHandler)completion {
  if (self.initError) {
    completion(nil, self.initError);
    return;
  }
  @try {
    // Collect and encrypt the signals.
    NSString *signals = ...
    // Pass the encrypted signals to IMA SDK.
    completion(signals, nil);
  }
  @catch(NSException *exception) {
    NSError *collectSignalError = ...;
    // Pass signal collection failures to IMA SDK.
    completion(nil, collectSignalError);
  }
}
/**
* @return The version of this adapter.
*         IMA SDK calls this function before each ad request.
*/
+ (IMAVersion *)adapterVersion {
  // The version of the SecureSignals Adapter.
  IMAVersion *adapterVersion = [[IMAVersion alloc] init];
  adapterVersion.majorVersion = VersionMajor;
  adapterVersion.minorVersion = VersionMinor;
  adapterVersion.patchVersion = VersionPatch;
  return adapterVersion;
}

/**
  * @return The version of your SDK that this adapter depends on.
  *         IMA SDK calls this function before each ad request.
  */
+ (IMAVersion *)adSDKVersion {
  // Request the version from your SDK and convert to an IMAVersion.
  int mySDKVersion[3] = ...

  IMAVersion *adSDKVersion = [[IMAVersion alloc] init];
  adSDKVersion.majorVersion = mySDKVersion[0];
  adSDKVersion.minorVersion = mySDKVersion[1];
  adSDKVersion.patchVersion = mySDKVersion[2];

  return adSDKVersion;
}

@end

Swift 

@objc(MySecureSignalsAdapter)
public class MySecureSignalsAdapter: IMASecureSignalsAdapter {
  static let VersionMajor = 1;
  static let VersionMinor = 0;
  static let VersionPatch = 1;

  private var initError

  override init() {
    super.init()

    do {
      // Initialize your SDK and any dependencies.
      ...
    } catch {
      // Build NSError to be passed by Signal Collector.
      self.initError = ...;
    }
  }

  public func collectSignals(completion: @escaping IMASignalCompletionHandler) {
    if (self.initError) {
      completion(nil, self.initError)
      return
    }

    do {
      // Collect and encrypt the signals.
      var signals = ...
      // Pass the encrypted signals to IMA SDK.
      completion(signals, nil)
    } catch {
      NSError collectSignalError = ...
      // Pass signal collection failures to IMA SDK.
      completion(nil, collectSignalError)
    }      
  }

  public static func adapterVersion() -> IMAVersion {
    let adapterVersion = IMAVersion()
    adapterVersion.majorVersion = self.VersionMajor
    adapterVersion.minorVersion = self.VersionMinor
    adapterVersion.patchVersion = self.VersionPatch
    return adapterVersion
  }

  public static func adSDKVersion() -> IMAVersion {
    // Request the version from your SDK and convert to an IMAVersion.
    let mySDKVersion = ...

    let adSDKVersion = IMAVersion()
    adSDKVersion.majorVersion = mySDKVersion[0]
    adSDKVersion.minorVersion = mySDKVersion[1]
    adSDKVersion.patchVersion = mySDKVersion[2]
    return adSDKVersion
  }
}