보안 처리된 신호 어댑터 만들기

보안 처리된 신호는 클라이언트 기기가 수집하여 선택한 입찰자와 공유하는 인코딩된 데이터입니다. 이 페이지에서는 양방향 미디어 광고 (IMA) SDK를 사용하여 보안 처리된 신호를 수집하고 Google Ad Manager에 전송하는 방법을 안내합니다.

시작하기 전에

계속하기 전에 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는 어댑터의 초기화 메서드를 호출하여 각 어댑터를 한 번 초기화합니다. 이 메서드를 구현하여 암호화 종속 항목을 시작하거나, 캐시를 설정하거나, 모든 신호 수집 호출에서 동일하게 유지되는 신호를 미리 계산합니다.

다음 예시는 어댑터를 초기화합니다.

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를 포드 파일에 추가합니다.

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