セキュア シグナル アダプターを作成する

セキュア シグナルは、クライアント デバイスが収集して一部の入札者と共有するエンコードされたデータです。このページでは、Interactive Media Ads（IMA）SDK を使用してセキュア シグナルを収集し、Google アド マネージャーに送信する方法について説明します。

始める前に

続行する前に、iOS 向け IMA SDK v3.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 は、アダプタの初期化メソッドを呼び出すことで、各アダプタを 1 回初期化します。このメソッドを実装して、暗号化の依存関係を開始したり、キャッシュを設定したり、すべてのシグナル収集呼び出しで同じままのシグナルを事前に計算したりします。

次の例では、アダプターを初期化します。

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 はシグナルの収集メソッドを非同期で呼び出します。これらのシグナル コレクタ メソッドには、暗号化されたシグナルを渡すか、エラーを報告するコールバック関数が含まれています。

注: 500 ミリ秒以内に、シグナルの収集と暗号化を完了し、暗号化されたシグナルをコールバック関数に渡す必要があります。500 ミリ秒後、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 ランタイム バージョンをリクエストして返します。

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

アダプタを Google に登録する

Google がシグナル収集用のアダプタを承認するには、iOS クラス名を Google に登録する必要があります。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
  }
}