Guida per gli sviluppatori dell'API Topics

Mentre leggi la documentazione di Privacy Sandbox su Android, utilizza il pulsante Anteprima per sviluppatori o Beta per selezionare la versione del programma che stai utilizzando, poiché le istruzioni possono variare.

Inviare feedback

L'API Topics deduce indicatori di interesse generali on-device in base all'utilizzo dell'app da parte dell'utente. Questi indicatori, chiamati argomenti, vengono condivisi con gli inserzionisti per supportare la pubblicità basata sugli interessi senza monitorare i singoli utenti nelle varie app. Scopri di più sull'API Topics nella proposta di progettazione. Importante: seleziona il pulsante Release estensioni SDK o Anteprima sviluppatore per scegliere la versione del programma a cui stai lavorando, in quanto le istruzioni possono variare.

Configurazione

Utilizza l'SDK Privacy Sandbox di Android più recente per ottenere la versione più aggiornata delle API incentrate sulla tutela della privacy. Per poter utilizzare l'API Topics, devi includere un'autorizzazione e creare una configurazione di servizi pubblicitari nel file manifest della tua app:

<uses-permission android:name="android.permission.ACCESS_ADSERVICES_TOPICS" />

Fai riferimento a una configurazione di servizi pubblicitari nell'elemento <application> del manifest:

<property android:name="android.adservices.AD_SERVICES_CONFIG"
   android:resource="@xml/ad_services_config" />

Specifica la risorsa XML dei servizi pubblicitari a cui viene fatto riferimento nel manifest, ad esempio res/xml/ad_services_config.xml. Utilizza l'attributo allowAllToAccess per concedere l'accesso a tutti gli SDK o l'attributo allowSdksToAccess per concedere l'accesso a singoli SDK. Scopri di più sulle autorizzazioni per i servizi pubblicitari e sul controllo dell'accesso agli SDK.

<ad-services-config>
    <topics allowAllToAccess="true" />
</ad-services-config>

Inoltre, devi abilitare l'accesso all'API Topics (disabilitata per impostazione predefinita) con questi comandi adb.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

La funzionalità principale dell'API Topics si trova nel metodo getTopics() all'interno dell'oggetto TopicsManager, come mostrato in questo esempio:

Kotlin 

fun getTopics(
        getTopicsRequest: GetTopicsRequest,
        executor: Executor,
        callback: OutcomeReceiver<GetTopicsResponse, Exception>
    ) { }

Java 

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

Per utilizzare questo metodo, inizializza l'oggetto TopicsManager e i parametri necessari per ricevere i dati degli argomenti. GetTopicsRequest passa le informazioni necessarie per recuperare i dati dell'API Topics, incluso un flag per indicare se il chiamante agirà come osservatore o meno. Se non agisce come un osservatore, la chiamata getTopics restituisce un argomento dell'epoca precedente, ma non influirà sui dati relativi agli argomenti di quello successivo. Il callback OutcomeReceiver gestisce il risultato in modo asincrono. Ad esempio:

Kotlin 

private fun topicGetter() {
    val mContext = baseContext
    val mTopicsManager = mContext.getSystemService(TopicsManager::class.java)
    val mExecutor: Executor = Executors.newCachedThreadPool()
    val shouldRecordObservation = false
    val mTopicsRequestBuilder: GetTopicsRequest.Builder = GetTopicsRequest.Builder()
    mTopicsRequestBuilder.setAdsSdkName(baseContext.packageName)
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation)
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, Exception>)
}
private var mCallback: OutcomeReceiver<GetTopicsResponse, java.lang.Exception> =
object : OutcomeReceiver<GetTopicsResponse, java.lang.Exception> {
    override fun onResult(result: GetTopicsResponse) {
        // handle successful result
        val topicsResult = result.topics
        for (i in topicsResult.indices) {
            Log.i("Topic", topicsResult[i].getTopicId().toString())
        }
        if (topicsResult.size == 0) {
            Log.i("Topic", "Returned Empty")
        }
    }
    override fun onError(error: java.lang.Exception) {
        // handle error
        Log.i("Topic", "Error, did not return successfully")
    }
}

Java 

public void TopicGetter() {
    @NonNull Context mContext = getBaseContext();
    TopicsManager mTopicsManager = mContext.getSystemService(TopicsManager.class);
    Executor mExecutor = Executors.newCachedThreadPool();
    boolean shouldRecordObservation = false;
    GetTopicsRequest.Builder mTopicsRequestBuilder = new GetTopicsRequest.Builder();
    mTopicsRequestBuilder.setAdsSdkName(getBaseContext().getPackageName());
    mTopicsRequestBuilder.setShouldRecordObservation(shouldRecordObservation);
    mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);
}
OutcomeReceiver mCallback = new OutcomeReceiver<GetTopicsResponse, Exception>() {
    @Override
    public void onResult(@NonNull GetTopicsResponse result) {
        //Handle Successful Result
        List<Topic> topicsResult = result.getTopics();
        for (int i = 0; i < topicsResult.size(); i++) {
            Log.i("Topic", topicsResult.get(i).getTopicId().toString());
        }
        if (topicsResult.size() == 0) {
            Log.i("Topic", "Returned Empty");
        }
    }
    @Override
    public void onError(@NonNull Exception error) {
        // Handle error
        Log.i("Topic", "Experienced an error, and did not return successfully");
    }
};

Richiedere un insieme di argomenti

Quando la configurazione è pronta, puoi effettuare una chiamata per ricevere un GetTopicsResponse come risultato del metodo getTopics():

Kotlin 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor,
        mCallback as OutcomeReceiver<GetTopicsResponse, java.lang.Exception>)

Java 

mTopicsManager.getTopics(mTopicsRequestBuilder.build(), mExecutor, mCallback);

La chiamata precedente fornirà un elenco di oggetti Topics contenenti valori ID che corrispondono ad argomenti nella tassonomia open source che sono pertinenti per l'utente o un errore pertinente. Gli argomenti saranno simili a quelli nell'esempio seguente:

/Internet & Telecom/Text & Instant Messaging

Fai riferimento alla tassonomia per un elenco di possibili argomenti che è possibile restituire. Questa tassonomia è open source e le modifiche suggerite possono essere presentate utilizzando il pulsante di feedback nella parte superiore di questa pagina.

Test

L'API Topics fornisce argomenti pertinenti e aggiornati in base all'utilizzo delle app. Questa versione in anteprima offre un'anteprima dei comportamenti dell'API e miglioreremo la qualità degli argomenti nelle release future. Per un'esperienza ottimale, consigliamo un ambiente di test con più app in cui chiami getTopics() per verificare come vengono selezionati gli argomenti. Il repository di API Runtime e Privacy Preserve SDK su GitHub contiene un set di singoli progetti Android Studio per aiutarti a iniziare, inclusi esempi che mostrano come inizializzare e chiamare l'API Topics.

Il calcolo degli argomenti avviene alla fine di un'"epoca". Per impostazione predefinita, ogni epoca dura 7 giorni, ma puoi modificare questo intervallo per ottenere un risultato. Questo comando shell di Android Debug Bridge riduce la durata dell'epoca a 5 minuti:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

Puoi confermare il valore topics_epoch_job_period_ms con get:

adb shell device_config get adservices topics_epoch_job_period_ms

Per attivare manualmente il calcolo epoch, esegui questo comando:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 2

Oltre a utilizzare l'app di esempio, è disponibile una Colab che puoi utilizzare per testare diverse combinazioni di informazioni sull'app rispetto al classificatore Argomenti. Utilizza questo Colab per visualizzare i tipi di risultati che la tua app potrebbe ricevere quando chiami getTopics.

Limitazioni

Per un elenco delle funzionalità in corso per l'API Topics, consulta le note di rilascio.

Segnalazione di bug e problemi

Il tuo feedback è una parte fondamentale di Privacy Sandbox su Android. Comunicaci eventuali problemi riscontrati o idee per migliorare Privacy Sandbox su Android.