Criar um adaptador de indicadores seguros

Importante: os indicadores seguros estão na versão Beta. Este documento é destinado apenas a parceiros selecionados. Não distribua este documento sem a autorização do Google.

Os indicadores seguros são dados codificados que um dispositivo cliente coleta e compartilha com bidders selecionados. Esta página orienta você sobre como coletar e enviar indicadores seguros para o Google Ad Manager usando o SDK do Interactive Media Ads (IMA).

Antes de começar

Antes de continuar, verifique se você tem o SDK do IMA para iOS v3.18.5 ou mais recente.

Criar a interface do adaptador de indicador seguro

Para coletar e fornecer indicadores seguros, crie classes que implementem a interface:

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

Inicializar o adaptador

O SDK do IMA inicializa cada adaptador uma vez chamando o método de inicialização do adaptador. Implemente esse método para iniciar dependências de criptografia, configurar caches ou pré-calcular qualquer sinal que permaneça o mesmo em todas as chamadas de coleta de sinais.

O exemplo a seguir inicializa o 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 = ...;
    }
  }
}

Coleta de indicadores

Antes de uma solicitação de anúncio ser iniciada, o SDK do IMA chama um método de coleta de indicadores de forma assíncrona. Esses métodos de coletor de indicadores contêm uma função de callback para transmitir os indicadores criptografados ou informar um erro.

Observação: em 500 milissegundos, você precisa concluir a coleta e a criptografia do sinal e transmitir o sinal criptografado para a função de callback. Após 500 milissegundos, o SDK do IMA descarta qualquer coleta de indicadores.

Os exemplos abaixo coletam os indicadores seguros usando a função de callback:

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

Relatar erros

Para se comunicar com os usuários que usam a classe do adaptador, informe todos os erros durante a coleta de indicadores e os transmita para o callback do coletor de indicadores. Esse processo resolve problemas que ocorrem durante a integração do adaptador a aplicativos.

Os erros que podem aparecer são os seguintes:

• O SDK ou uma dependência não foi encontrado no aplicativo.
• Seu SDK ou uma dependência não tem a permissão ou o consentimento do usuário necessário para funcionar.

Especificar a versão do adaptador

No seu fluxo de trabalho, especifique a versão do adaptador. O SDK do IMA inclui a versão do adaptador em cada solicitação de anúncio e as transmite com os indicadores seguros em uma solicitação de lance.

Na solicitação de lance, com base na versão do adaptador, é possível identificar os detalhes de criptografia, codificação e formatação que o adaptador usa para criar os sinais seguros.

O exemplo a seguir especifica a versão do 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
  }
...

Retornar a versão do SDK Runtime

É possível projetar o adaptador para funcionar com várias versões do SDK. Para que o adaptador funcione com várias versões, retorne a versão do ambiente de execução do SDK. Em cada solicitação de anúncio, o SDK do IMA inclui a versão do ambiente de execução com a versão do adaptador.

Os exemplos a seguir solicitam e retornam a versão do ambiente de execução do 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
  }
...

Registrar o adaptador com o Google

Para que o Google autorize o adaptador para a coleta de indicadores, você precisa registrar o nome da classe do iOS com o Google. O SDK do IMA inicializa somente os adaptadores que você registra no Google.

Validar o adaptador

Para validar o adaptador, conclua as seguintes seções:

Configurar o aplicativo de teste

Antes de validar o adaptador, configure o aplicativo de teste. Conclua as etapas a seguir:

1. Adicione o SDK do IMA ao arquivo do pod:

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

2. Instale o SDK do IMA usando o CocoaPods. Para instruções sobre como instalar o SDK do IMA pelo CocoaPods, consulte Começar.

3. No projeto do XCode, adicione o adaptador, o SDK e todas as dependências de build adicionadas.

Verificar os indicadores

Para verificar o comprimento do indicador seguro, o valor criptografado, a versão do adaptador e a versão do SDK, entre em contato com o suporte para compartilhar o registro de tráfego capturado.

Analise os exemplos completos

Esta seção mostra o exemplo completo de todas as etapas e está disponível para sua referência.

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