Crea un adaptador de indicadores seguros

Los indicadores seguros son datos codificados que un dispositivo cliente recopila y comparte con ofertantes seleccionados. En esta página, se explica cómo recopilar y enviar indicadores seguros a Google Ad Manager con el SDK de Interactive Media Ads (IMA).

Antes de comenzar

Antes de continuar, verifica que tengas el SDK de IMA para Android v3.29.0 o una versión posterior.

Crea la interfaz del adaptador de indicador seguro

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

Nota: El SDK de IMA carga tu clase de adaptador con la reflexión. Para evitar la eliminación del código reducido en el momento de la compilación, agrega la anotación de Android @Keep a tu clase.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
}

Inicializa 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 cualquier dependencia de encriptación, configurar cachés o precalcular cualquier indicador que permanezca igual en todas las llamadas de recopilación de indicadores.

En el siguiente ejemplo, se inicializa el adaptador:

  ...
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    // Initialize your SDK and any dependencies.
    ...

    // Notify IMA SDK of initialization success.
    callback.onSuccess();

    // If signal collection fails, call callback.onFailure();
    // callback.onFailure(new Exception("Signal collection failed."));
  }
  ...

Recopilación de indicadores

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 recopilación de señales 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 encriptación de la señal, y pasar la señal encriptada a la función de devolución de llamada. Después de 500 milisegundos, el SDK de IMA descarta cualquier recopilación de señales.

En los siguientes ejemplos, se recopilan los indicadores seguros a través de la función de devolución de llamada:

  ...
  /**
   * 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 context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {

    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  ...

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 de tu adaptador en las aplicaciones.

Los errores que pueden aparecer son los siguientes:

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

Cómo especificar la versión del adaptador

En tu flujo de trabajo, verifica que especifiques la versión del adaptador. El SDK de IMA incluye la versión de tu adaptador en cada solicitud de anuncio y las 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 usa el adaptador para crear los indicadores seguros.

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

  ...
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  ...
  /**
   * @return The version of this adapter.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  ...

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

Puedes diseñar tu adaptador para que funcione con varias versiones de tu SDK. Para que el adaptador funcione con varias versiones, verifica que devuelvas la versión de tiempo 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 se devuelve la versión del tiempo de ejecución del SDK:

  ...
  /**
   * @return The version of your SDK that this adapter is depending on.
   *         IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;

    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
  ...

Registra el adaptador en Google

Para que Google autorice el adaptador para la recopilación de indicadores, debes registrar el nombre del paquete de Android o el ID de paquete de iOS en Google. El SDK de IMA solo inicializa los adaptadores que registras en 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 las dependencias del SDK de IMA al archivo Gradle a nivel de la app de tu módulo, como app/build.gradle:

   dependencies {
     implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0'
   }
   

2. Agrega dependencias de compilación, como tu adaptador y SDK.

Verifica los indicadores

Para verificar que tu adaptador envíe indicadores, usa un proxy de red para supervisar el tráfico de solicitudes de anuncios de tu aplicación. Si la operación se realiza correctamente, verás los indicadores en cada solicitud de anuncio.

Revisa los ejemplos completos

En esta sección, se muestra el ejemplo completo de todos los pasos, que puedes consultar.

package companydomain.path.to.securesignals;
import android.content.Context;
import androidx.annotation.Keep;
import com.google.ads.interactivemedia.v3.api.VersionInfo;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsAdapter;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsCollectSignalsCallback;
import com.google.ads.interactivemedia.v3.api.signals.SecureSignalsInitializeCallback;

/**
 * An example implementation of Secure Signals adapter.
 */
@Keep
public final class MySecureSignalsAdapter implements SecureSignalsAdapter {
  /**
   * Specifies this adapter's version.
   */
  private static final VersionInfo AdapterVersion = new VersionInfo(1, 0, 1);
  /**
   * Default constructor with no arguments for IMA SDK to instantiate this class.
   */
  public MySecureSignalsAdapter() {
  }
  /**
   * Initialize your SDK and any dependencies.
   * IMA SDK calls this function exactly once before signal collection.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass initialization results to IMA SDK.
   */
  @Override
  public void initialize(Context context, SecureSignalsInitializeCallback callback) {
    try {
      // Initialize your SDK and any dependencies.
      ...

      // Notify IMA SDK of initialization success.
      callback.onSuccess();
    } catch (Exception e) {
      // Pass initialization failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * Invokes your SDK to collect, encrypt and send the signal collection results to IMA SDK.
   * IMA SDK calls this function before each ad request.
   *
   * @param context  The activity context that creates an ads loader.
   * @param callback A callback function to pass signal collection results to IMA SDK.
   */
  @Override
  public void collectSignals(Context context, SecureSignalsCollectSignalsCallback callback) {
    try {
      // Collect and encrypt the signals.
      String signals = ...;

      // Pass the encrypted signals to IMA SDK.
      callback.onSuccess(signals);
    } catch (Exception e) {
      // Pass signal collection failures to IMA SDK.
      callback.onFailure(e);
    }
  }
  /**
   * @return The version of this adapter.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getVersion() {
    return AdapterVersion;
  }
  /**
   * @return The version of your SDK that this adapter is depending on.
   * IMA SDK calls this function before each ad request.
   */
  @Override
  public VersionInfo getSDKVersion() {
    // Request the version from your SDK and convert to an IMAVersion.
    int[] mySDKVersion = ...;
    return new VersionInfo(mySDKVersion[0], mySDKVersion[1], mySDKVersion[2]);
  }
}