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.
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.
Consigliati per te
- Nota: il testo del link viene visualizzato quando JavaScript è disattivato
- Guida per gli sviluppatori sull'API Protected Audience su Android
- Note di rilascio
- Configura AdServices {:#configure-adservices}