Adapter für sichere Signale erstellen

Sichere Signale sind codierte Daten, die von einem Clientgerät erhoben und für ausgewählte Bieter freigegeben werden. Auf dieser Seite erfahren Sie, wie Sie mit dem Interactive Media Ads (IMA) SDK sichere Signale für Google Ad Manager erfassen und senden.

Hinweis

Prüfen Sie, ob Sie das IMA SDK für iOS v3.18.5 oder höher verwenden.

Schnittstelle für sicheren Signaladapter erstellen

Um sichere Signale zu erfassen und bereitzustellen, erstellen Sie Klassen, die die Schnittstelle implementieren:

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

Adapter initialisieren

Das IMA SDK initialisiert jeden Adapter einmal, indem es die Initialisierungsmethode des Adapters aufruft. Implementieren Sie diese Methode, um alle Verschlüsselungsabhängigkeiten zu starten, Caches einzurichten oder Signale vorzuberechnen, die in allen Aufrufen zur Signalerhebung gleich bleiben.

Im folgenden Beispiel wird der Adapter initialisiert:

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

Signalerfassung

Bevor eine Anzeigenanfrage gesendet wird, ruft das IMA SDK asynchron eine Methode zum Erfassen von Signalen auf. Diese Methoden zum Erfassen von Signalen enthalten eine Callback-Funktion, mit der die verschlüsselten Signale übergeben oder ein Fehler gemeldet wird.

In den folgenden Beispielen werden die sicheren Signale über die Callback-Funktion erfasst:

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

Berichtsfehler

Wenn Sie mit Nutzern kommunizieren möchten, die Ihre Adapterklasse verwenden, müssen Sie alle Fehler während der Signalerfassung melden und an den Callback des Signal Collectors übergeben. Mit diesem Prozess werden Probleme behoben, die bei der Integration Ihres Adapters in Anwendungen auftreten.

Folgende Fehler können auftreten:

  • Ihr SDK oder eine Abhängigkeit wurde in der Anwendung nicht gefunden.
  • Für Ihr SDK oder eine Abhängigkeit sind nicht die erforderlichen Berechtigungen oder die Einwilligung des Nutzers vorhanden.

Adapterversion angeben

Prüfen Sie, ob Sie in Ihrem Workflow die Version des Adapters angeben. Das IMA SDK fügt jeder Anzeigenanfrage Ihre Adapterversion hinzu und übergibt sie zusammen mit den sicheren Signalen in einer Gebotsanfrage.

In der Gebotsanfrage können Sie anhand der Adapterversion die Verschlüsselungs-, Codierungs- und Formatierungsdetails ermitteln, die der Adapter zum Erstellen der sicheren Signale verwendet.

Im folgenden Beispiel wird die Adapterversion angegeben:

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-Laufzeitversion zurückgeben

Sie können Ihren Adapter so gestalten, dass er mit mehreren Versionen Ihres SDK funktioniert. Damit der Adapter mit mehreren Versionen funktioniert, müssen Sie die Laufzeitversion des SDK zurückgeben. Das IMA SDK enthält in jeder Anzeigenanfrage die Laufzeitversion mit der Adapterversion.

In den folgenden Beispielen wird die SDK-Laufzeitversion angefordert und zurückgegeben:

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

Adapter bei Google registrieren

Damit Google den Adapter für die Signalerfassung autorisieren kann, müssen Sie den iOS-Klassennamen bei Google registrieren. Das IMA SDK initialisiert nur die Adapter, die Sie bei Google registrieren.

Adapter validieren

Führen Sie die folgenden Schritte aus, um den Adapter zu validieren:

Testanwendung konfigurieren

Bevor Sie den Adapter validieren, müssen Sie die Testanwendung konfigurieren. Gehen Sie folgendermaßen vor:

  1. Fügen Sie Ihrer Pod-Datei das IMA SDK hinzu:

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

  2. Installieren Sie das IMA SDK mit CocoaPods. Eine Anleitung zur Installation des IMA SDK über CocoaPods finden Sie unter Erste Schritte.

  3. Fügen Sie Ihrem Xcode-Projekt Ihren Adapter, Ihr SDK und alle verbleibenden Build-Abhängigkeiten hinzu, die Sie hinzugefügt haben.

Signale überprüfen

Wenn Sie die Länge des sicheren Signals, den verschlüsselten Wert, die Adapterversion und die SDK-Version überprüfen möchten, wenden Sie sich an den Support und geben Sie das erfasste Traffic-Log an.

Vollständige Beispiele ansehen

In diesem Abschnitt finden Sie das vollständige Beispiel für alle Schritte.

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