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

Tín hiệu an toàn là dữ liệu được mã hoá mà thiết bị của ứng dụng 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 cách 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 xác minh rằng bạn có IMA SDK 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 an toàn

Để 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 từng 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 khởi chạy bộ 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 yêu cầu quảng cáo bắt đầu, IMA SDK sẽ gọi một phương thức thu thập tín hiệu 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.

Lưu ý: Trong vòng 500 mili giây, bạn phải hoàn tất quá trình thu thập tín hiệu, mã hoá và truyền tín hiệu đã mã hoá đến hàm gọi lại. Sau 500 mili giây, SDK IMA sẽ loại bỏ mọi hoạt động thu thập tín hiệu.

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 của bạn, hãy báo cáo tất cả lỗi trong quá trình thu thập tín hiệu và truyề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 vấn đề xảy ra trong quá trình tích hợp bộ chuyển đổi vào các ứng dụng.

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

• Không tìm thấy SDK hoặc một phần phụ thuộc trong ứng dụng.
• SDK hoặc một phần phụ thuộc của bạn không có quyền cần thiết hoặ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 xác minh rằng bạn chỉ định phiên bản của bộ chuyển đổi. SDK IMA sẽ đưa phiên bản bộ chuyển đổi của bạn vào từng yêu cầu quảng cáo và truyền các phiên bản đó cùng với các tín hiệu an toàn trong một yêu cầu giá thầu.

Trong yêu cầu đặt 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ề hoạt động mã hoá, mã hoá và định dạng mà bộ chuyển đổi dùng để tạo các tín hiệu an toàn.

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 xác minh rằng 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 sẽ bao gồm phiên bản thời gian chạy cùng 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ý đối tượng 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 những 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 tất các phần sau:

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

Trước khi bạn 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 IMA SDK 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 IMA SDK bằng CocoaPods. Để biết hướng dẫn về cách 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 bộ chuyển đổi, SDK và mọi phần phụ thuộc còn lại của bản dựng 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ị đã mã hoá, phiên bản bộ chuyển đổi và phiên bản SDK, hãy liên hệ với nhóm hỗ trợ để chia sẻ nhật ký lưu lượng truy cập đã ghi lại.

Xem các ví dụ đầy đủ

Phần này trình bày ví dụ hoàn chỉnh về tất cả các bước để 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
  }
}