Crea un adaptador de indicadores seguros

Importante: Los indicadores seguros se encuentran en versión beta. Este documento está destinado solo a socios seleccionados. No distribuyas este documento sin la autorización de Google.

Los indicadores seguros son datos codificados que un dispositivo cliente recopila y comparte con ofertantes seleccionados. En esta página, se te guía para recopilar y enviar indicadores seguros a Google Ad Manager con el SDK de anuncios multimedia interactivos (IMA).

Antes de comenzar

Antes de continuar, asegúrate de tener el SDK de IMA para iOS 3.18.5 o una versión posterior.

Cómo crear la interfaz del adaptador de indicadores seguros

Para recopilar y proporcionar indicadores seguros, crea clases que implementen la interfaz:

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

Cómo inicializar el adaptador

El SDK de IMA inicializa cada adaptador una vez llamando al método de inicialización del adaptador. Implementa este método para iniciar dependencias de encriptación, configurar cachés o precalcular los indicadores que permanecen iguales en todas las llamadas de recopilación de indicadores.

En el siguiente ejemplo, se inicializa el adaptador:

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

Recopilación de señal

Antes de que se inicie una solicitud de anuncio, el SDK de IMA llama a un método de recopilación de indicadores de forma asíncrona. Estos métodos de captador de indicadores contienen una función de devolución de llamada para pasar las señales encriptadas o informar un error.

Nota: En un plazo de 500 milisegundos, debes completar la recopilación y la encriptación de los indicadores, y pasar el indicador encriptado a la función de devolución de llamada. Después de 500 milisegundos, el SDK de IMA descarta cualquier recopilación de indicadores.

En los siguientes ejemplos, se recopilan los indicadores seguros mediante la función de devolución de llamada:

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

Informa errores

Para comunicarte con los usuarios que usan tu clase de adaptador, informa todos los errores durante la recopilación de indicadores y pásalos a la devolución de llamada del recopilador de indicadores. Este proceso soluciona los problemas que se producen durante la integración del adaptador a las aplicaciones.

Los errores que pueden aparecer son los siguientes:

• No se encontró tu SDK o una dependencia en la aplicación.
• Tu SDK o una dependencia no tienen el permiso requerido ni el consentimiento del usuario para funcionar.

Especifica la versión del adaptador

En tu flujo de trabajo, asegúrate de especificar la versión del adaptador. El SDK de IMA incluye la versión de tu adaptador en cada solicitud de anuncio y la pasa con los indicadores seguros en una solicitud de oferta.

En la solicitud de oferta, según la versión del adaptador, puedes identificar los detalles de encriptación, codificación y formato que el adaptador usa para crear los indicadores seguros.

En el siguiente ejemplo, se especifica la versión del adaptador:

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

Devuelve la versión del entorno de ejecución del SDK

Puedes diseñar tu adaptador para que funcione con varias versiones del SDK. Para que el adaptador funcione con varias versiones, asegúrate de mostrar la versión del entorno de ejecución del SDK. En cada solicitud de anuncio, el SDK de IMA incluye la versión del entorno de ejecución con la versión del adaptador.

En los siguientes ejemplos, se solicita y muestra la versión del entorno de ejecución del 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
  }
...

Registra el adaptador con Google

Para que Google autorice el adaptador para la recopilación de indicadores, debes registrar el nombre de la clase de iOS con Google. El SDK de IMA solo inicializa los adaptadores que registras con Google.

Valida el adaptador

Para validar el adaptador, completa las siguientes secciones:

Configura la aplicación de prueba

Antes de validar el adaptador, configura la aplicación de prueba. Completa los siguientes pasos:

1. Agrega el SDK de IMA a tu archivo pod:

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

2. Instalar el SDK de IMA con CocoaPods Para obtener instrucciones sobre cómo instalar el SDK de IMA con CocoaPods, consulta Cómo comenzar.

3. En tu proyecto de Xcode, agrega el adaptador, el SDK y las dependencias de compilación restantes que agregaste.

Verifica los indicadores

Para verificar la longitud del indicador seguro, el valor encriptado, la versión del adaptador y la versión del SDK, comunícate con el equipo de asistencia para compartir el registro de tráfico capturado.

Revisa los ejemplos completos

En esta sección, se captura el ejemplo completo de todos los pasos y está disponible para tu referencia.

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