Gli indicatori sicuri sono dati codificati raccolti e condivisi da un dispositivo client con offerenti selezionati. Questa pagina ti guida nella raccolta e nell'invio di indicatori sicuri a Google Ad Manager utilizzando l'SDK Interactive Media Ads (IMA).
Prima di iniziare
Prima di continuare, assicurati di avere l'SDK IMA per Android 3.29.0 o versioni successive.
Crea l'interfaccia dell'adattatore di indicatore sicuro
Per raccogliere e fornire indicatori sicuri, crea classi che implementano l'interfaccia:
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() {
}
}
Inizializza l'adattatore
L'SDK IMA inizializza ogni adattatore una volta richiamando il metodo di inizializzazione dell'adattatore. Implementa questo metodo per avviare eventuali dipendenze di crittografia, impostare le cache o precalcolare gli indicatori che rimangono invariati in tutte le chiamate di raccolta degli indicatori.
Nell'esempio seguente l'adattatore viene inizializzato:
...
/**
* 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."));
}
...
Raccolta di indicatori
Prima dell'avvio di una richiesta di annuncio, l'SDK IMA chiama un metodo di raccolta dei dati in modo asincrono. Questi metodi di raccolta degli indicatori contengono una funzione di callback per trasmettere gli indicatori criptati o segnalare un errore.
I seguenti esempi raccolgono gli indicatori sicuri tramite la funzione di 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);
}
}
...
Segnalare errori
Per comunicare con gli utenti che utilizzano la tua classe di adattatore, segnala tutti gli errori durante la raccolta degli indicatori e trasmettili al callback del raccoglitore di indicatori. Questo procedura consente di risolvere i problemi che si verificano durante l'integrazione dell'adattatore con le applicazioni.
Gli errori che potrebbero essere visualizzati sono i seguenti:
- Impossibile trovare l'SDK o una dipendenza nell'applicazione.
- Il tuo SDK o una dipendenza non dispone dell'autorizzazione o del consenso dell'utente necessario per il funzionamento.
Specifica la versione dell'adattatore
Nel flusso di lavoro, assicurati di specificare la versione dell'adattatore. L'SDK IMA include la versione dell'adattatore in ogni richiesta di annuncio e la passa con gli indicatori sicuri in una richiesta di offerta.
Nella richiesta di offerta, in base alla versione dell'adattatore, puoi identificare i dettagli di crittografia, codifica e formattazione utilizzati dall'adattatore per creare gli indicatori sicuri.
L'esempio seguente specifica la versione dell'adattatore:
...
/**
* 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;
}
...
Restituisce la versione del runtime dell'SDK
Puoi progettare l'adattatore in modo che funzioni con più versioni dell'SDK. Affinché l'adattatore funzioni con più versioni, assicurati di restituire la versione runtime dell'SDK. In ogni richiesta di annuncio, l'SDK IMA include la versione di runtime con la versione dell'adattatore.
I seguenti esempi richiedono e restituiscono la versione del runtime dell'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 l'adattatore con Google
Affinché Google autorizzi l'adattatore per la raccolta degli indicatori, devi registrare il nome del pacchetto Android o registrarti con Google. L'SDK IMA inizializza solo gli adattatori che registri con Google.
Convalida l'adattatore
Per convalidare l'adattatore, completa le seguenti sezioni:
Configura l'applicazione di test
Prima di convalidare l'adattatore, configura l'applicazione di test. Completa i seguenti passaggi:
Aggiungi le dipendenze per l'SDK IMA al file Gradle a livello di app del tuo modulo, ad esempio
app/build.gradle:dependencies { implementation 'com.google.ads.interactivemedia.v3:interactivemedia:3.29.0' }Aggiungi dipendenze per la build, ad esempio l'adattatore e l'SDK.
Verificare gli indicatori
Per verificare che l'adattatore invii gli indicatori, utilizza un proxy di rete per monitorare il traffico delle richieste di annunci della tua applicazione. Se l'operazione ha esito positivo, vedrai gli indicatori in ogni richiesta di annuncio.
Esamina gli esempi completi
Questa sezione mostra l'esempio completo di tutti i passaggi e può essere utilizzata come riferimento.
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]);
}
}