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 Android v3.29.0 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:
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 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:
...
/**
* 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."));
}
...
Captació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 recopilador de indicadores contienen una función de devolución de llamada para pasar los indicadores encriptados o informar un error.
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. Con este proceso, se solucionan los problemas que ocurren 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 ni el consentimiento del usuario necesarios 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 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;
}
...
Muestra 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, 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:
...
/**
* @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 con Google
Para que Google autorice el adaptador para la recopilación de indicadores, debes registrar el nombre del paquete de Android o con Google. El SDK de IMA solo inicializa los adaptadores que registras con Google.
Cómo validar 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:
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' }Agrega dependencias de compilación, como el adaptador y el SDK.
Verifica los indicadores
Para verificar que el adaptador envíe indicadores, usa un proxy de red para supervisar el tráfico de solicitudes de anuncios de tu aplicación. Si se realiza correctamente, verás los indicadores en cada solicitud de anuncios.
Revisa los ejemplos completos
En esta sección, se captura el ejemplo completo de todos los pasos y está disponible para tu referencia.
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]);
}
}