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 Android v3.29.0 ou mais recente.
Criar a interface do adaptador de indicador seguro
Para coletar e fornecer indicadores seguros, crie classes que implementem a interface:
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() {
}
}
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:
...
/**
* 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."));
}
...
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.
Os exemplos a seguir coletam os indicadores seguros pela função de callback:
...
/**
* 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);
}
}
...
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 app.
- 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 abaixo especifica a versão do 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;
}
...
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.
O exemplo a seguir solicita e retorna a versão do SDK Runtime:
...
/**
* @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]);
}
...
Registrar o adaptador com o Google
Para que o Google autorize o adaptador para a coleta de indicadores, registre o nome do pacote Android ou 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. Siga estas etapas:
Adicione as dependências do SDK do IMA ao arquivo do Gradle no nível do app do seu módulo, como
app/build.gradle:dependencies { implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0' }Adicione dependências do build, como o adaptador e o SDK.
Verificar os indicadores
Para verificar se o adaptador envia sinais, use um proxy de rede para monitorar o tráfego da solicitação de anúncio do seu aplicativo. Se for bem-sucedido, você vai ver os indicadores em cada solicitação de anúncio.
Analisar os exemplos completos
Esta seção mostra o exemplo completo de todas as etapas e está disponível para sua referência.
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]);
}
}