Adapter für sichere Signale erstellen

Wichtig :Sichere Signale befinden sich in der Betaphase. Dieses Dokument richtet sich nur an ausgewählte Partner. Dieses Dokument darf nicht ohne Genehmigung von Google verbreitet werden.

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

Hinweis

Bevor du fortfährst, musst du das IMA SDK für iOS 3.18.5 oder höher installiert haben.

Schnittstelle für sicheren Signaladapter erstellen

Wenn Sie sichere Signale erfassen und bereitstellen möchten, 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 Verschlüsselungsabhängigkeiten zu starten, Caches einzurichten oder Signale vorab zu berechnen, die in allen Aufrufen zur Signalerfassung 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 gestartet wird, ruft das IMA SDK asynchron eine Methode zum Erfassen von Signalen auf. Diese Methoden zum Erfassen von Signalen enthalten eine Callback-Funktion, um die verschlüsselten Signale weiterzuleiten oder einen Fehler zu melden.

Hinweis: Innerhalb von 500 Millisekunden müssen Sie die Signalerfassung und -verschlüsselung abschließen und das verschlüsselte Signal an die Callback-Funktion übergeben. Nach 500 Millisekunden verwirft das IMA SDK alle Signale.

In den folgenden Beispielen werden die sicheren Signale über die Rückruffunktion 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, melden Sie alle Fehler während der Signalerfassung und übergeben Sie sie an den Signal-Collector-Callback. Mit diesem Verfahren können Probleme behoben werden, die bei der Integration des Adapters in Anwendungen auftreten.

Mögliche Fehler:

• Ihr SDK oder eine Abhängigkeit wurde in der App nicht gefunden.
• Ihr SDK oder eine Abhängigkeit hat nicht die erforderliche Berechtigung oder Nutzereinwilligung, um zu funktionieren.

Adapterversion angeben

Geben Sie in Ihrem Workflow die Version des Adapters an. Das IMA SDK fügt deine Adapterversion in jede Anzeigenanfrage ein 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 angeben, 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 SDKs funktioniert. Damit der Adapter mit mehreren Versionen funktioniert, muss die Laufzeitversion des SDK zurückgegeben werden. In jeder Anzeigenanfrage enthält das IMA SDK 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 du bei Google registrierst.

Adapter prüfen

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

Testanwendung konfigurieren

Konfigurieren Sie die Testanwendung, bevor Sie den Adapter validieren. 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 zum Installieren des IMA SDK über CocoaPods findest du unter Einstieg.

3. Fügen Sie Ihrem XCode-Projekt den Adapter, das SDK und alle verbleibenden Buildabhängigkeiten hinzu, die Sie hinzugefügt haben.

Signale prüfen

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

Vollständige Beispiele ansehen

In diesem Abschnitt finden Sie das vollständige Beispiel mit allen Schritten, das als Referenz zur Verfügung steht.

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