建立安全信號轉接器

安全信號是用戶端裝置收集並與特定出價方分享的經編碼資料。本頁面將引導您使用互動式媒體廣告 (IMA) SDK，收集並傳送安全信號給 Google Ad Manager。

事前準備

繼續操作之前，請確認您已安裝 iOS 版 IMA SDK 3.18.5 以上版本。

建立安全信號轉接器介面

如要收集並提供安全信號，請建立實作介面的類別：

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()
  }
}

初始化轉接程式

IMA SDK 會呼叫轉接程式的初始化方法，初始化每個轉接程式一次。實作此方法可開始任何加密依附元件、設定快取，或預先計算所有信號收集呼叫中保持不變的信號。

以下範例會初始化轉接程式：

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

信號收集

在廣告請求啟動前，IMA SDK 會非同步呼叫收集信號方法。這些信號收集器方法包含回呼函式，可傳遞已加密的信號或回報錯誤。

以下範例會透過回呼函式收集安全信號：

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

回報錯誤

如要與使用您轉接程式類別的使用者通訊，請在信號收集期間回報所有錯誤，並將這些錯誤傳遞至信號收集器回呼。這個程序會排解在將轉接器整合至應用程式時發生的問題。

可能會顯示的錯誤如下：

  • 應用程式中找不到您的 SDK 或依附元件。
  • 您的 SDK 或依附元件不具備必要的權限或使用者同意聲明，無法執行。

指定轉接器版本

請務必在工作流程中指定轉接程式版本。IMA SDK 會在每個廣告請求中加入轉接程式版本，並透過出價要求中的安全信號傳遞。

在出價要求中，您可以根據轉接程式版本，找出轉接程式用於建立安全信號的加密、編碼和格式詳細資料。

以下範例會指定轉接器版本：

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

傳回 SDK 執行階段版本

您可以設計轉接程式，讓其支援多個 SDK 版本。為了讓轉接器支援多個版本，請務必傳回 SDK 的執行階段版本。在每個廣告請求中，IMA SDK 都會納入執行階段版本和轉接程式版本。

以下範例會要求並傳回 SDK 執行階段版本：

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

向 Google 註冊轉接器

如要讓 Google 授權適配器收集信號，您必須向 Google 註冊 iOS 類別名稱。IMA SDK 只會初始化您向 Google 註冊的轉接程式。

驗證轉接器

如要驗證轉接程式，請完成下列各節：

設定測試應用程式

在驗證轉接程式之前，請設定測試應用程式。請完成下列步驟：

  1. 將 IMA SDK 新增至 Pod 檔案：

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

  2. 使用 CocoaPods 安裝 IMA SDK。如需透過 CocoaPods 安裝 IMA SDK 的操作說明，請參閱「開始使用」一文。

  3. 在 XCode 專案中，新增適配器、SDK 和您新增的任何其他建構依附元件。

驗證信號

如要驗證安全信號的長度、加密值、轉接程式版本和 SDK 版本，請與支援團隊聯絡，分享擷取到的流量記錄。

查看完整範例

本節會擷取所有步驟的完成範例，供您參考。

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