Tworzenie adaptera bezpiecznych sygnałów

Ważne: sygnały bezpieczeństwa są w wersji beta. Ten dokument jest przeznaczony tylko dla wybranych partnerów. Nie rozpowszechniaj tego dokumentu bez zgody Google.

Bezpieczne sygnały to zakodowane dane, które urządzenie klienta zbiera i udostępnia wybranym licytującym. Na tej stronie znajdziesz wskazówki dotyczące zbierania i wysyłania bezpiecznych sygnałów do Google Ad Managera za pomocą pakietu Interactive Media Ads SDK.

Zanim zaczniesz

Zanim przejdziesz dalej, upewnij się, że masz pakiet IMA SDK dla iOS w wersji 3.18.5 lub nowszej.

Tworzenie interfejsu adaptera bezpiecznego sygnału

Aby zbierać i przekazywać bezpieczne sygnały, utwórz klasy, które implementują interfejs:

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

Inicjowanie adaptera

Pakiet IMA SDK inicjuje każdy adapter tylko raz, wywołując metodę inicjowania tego adaptera. Zastosowanie tej metody powoduje utworzenie zależności szyfrowania, ustawienie pamięci podręcznej lub wstępny przeliczanie sygnałów, które pozostają takie same we wszystkich wywołaniach funkcji zbierania sygnałów.

Ten przykład inicjuje adapter:

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

Zbieranie sygnałów

Przed rozpoczęciem żądania reklamy pakiet IMA SDK asynchronicznie wywołuje metodę collect signals. Te metody zbierania sygnałów zawierają funkcję wywołania zwrotnego, która przekazuje zaszyfrowane sygnały lub zgłasza błąd.

Uwaga: w ciągu 500 milisekund musisz przeprowadzić zbieranie i szyfrowanie sygnału oraz przekazać zaszyfrowany sygnał do funkcji wywołania zwrotnego. Po 500 milisekundach pakiet IMA SDK odrzuca wszystkie zebrane sygnały.

W tych przykładach bezpieczne sygnały są zbierane za pomocą funkcji wywołania zwrotnego:

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

Zgłaszanie błędów

Aby komunikować się z użytkownikami, którzy korzystają z Twojej klasy adaptera, zgłaszaj wszystkie błędy podczas zbierania sygnałów i przekazuj je do funkcji wywołania zwrotnego zbieracza sygnałów. Ten proces umożliwia rozwiązywanie problemów występujących podczas integracji adaptera z aplikacjami.

Mogą pojawić się takie błędy:

• Pakiet SDK lub zależność nie został znaleziony w aplikacji.
• Pakiet SDK lub jego zależność nie ma wymaganych uprawnień ani zgody użytkownika.

Określ wersję adaptera

W przepływie pracy pamiętaj, aby określić wersję adaptera. Pakiet IMA SDK uwzględnia wersję adaptera w każdym żądaniu reklamy i przekazuje ją wraz z bezpiecznymi sygnałami w żądaniu stawki.

W żądaniu stawki na podstawie wersji adaptera możesz określić szczegóły szyfrowania, kodowania i formatowania, których używa adapter do tworzenia bezpiecznych sygnałów.

W tym przykładzie określono wersję adaptera:

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

zwracać wersję pakietu SDK w czasie wykonywania;

Możesz zaprojektować adapter tak, aby działał z wieloma wersjami pakietu SDK. Aby adapter działał z wieloma wersjami, upewnij się, że zwracasz wersję środowiska wykonawczego pakietu SDK. W każdym żądaniu reklamy pakiet IMA SDK zawiera wersję runtime z wersją adaptera.

W tych przykładach żądana i zwracana jest wersja środowiska wykonawczego pakietu 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
  }
...

Rejestrowanie adaptera w Google

Aby Google autoryzował adapter do zbierania sygnałów, musisz zarejestrować nazwę klasy iOS w Google. Pakiet IMA SDK inicjuje tylko te adaptery, które zarejestrujesz w Google.

Sprawdzanie adaptera

Aby sprawdzić adapter, zapoznaj się z tymi sekcjami:

Konfigurowanie aplikacji testowej

Zanim zweryfikujesz adapter, skonfiguruj aplikację testową. Wykonaj te czynności:

1. Dodaj pakiet IMA SDK do pliku pod:

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

2. Zainstaluj pakiet IMA SDK za pomocą CocoaPods. Instrukcje instalowania pakietu IMA SDK za pomocą CocoaPods znajdziesz w artykule Pierwsze kroki.

3. W projekcie XCode dodaj adapter, pakiet SDK i pozostałe dodane przez Ciebie zależności kompilacji.

Weryfikowanie sygnałów

Aby zweryfikować długość sygnału zabezpieczającego, zaszyfrowaną wartość, wersję adaptera i wersję pakietu SDK, skontaktuj się z zespołem pomocy, aby udostępnić przechwycony dziennik ruchu.

Zapoznaj się z pełnymi przykładami

Ta sekcja zawiera przykładowe wykonanie wszystkich czynności i jest dostępna do wglądu.

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