Implementare l'API Topics su Android

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Configurazione

Per implementare l'API Topics, devi prima configurare il tuo ambiente di sviluppo. di eseguire la seguente procedura di configurazione:

1. Utilizza l'SDK Android Privacy Sandbox più recente per ottenere la versione più aggiornata delle API incentrate sulla tutela della privacy.

2. Aggiungi quanto segue al manifest:

   • Autorizzazione: includi l'autorizzazione ACCESS_ADSERVICES_TOPICS per consentire alla tua app di accedere all'API Topics:

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

   • Configurazione dei servizi pubblicitari: fai riferimento a un file di configurazione dei servizi pubblicitari nell'elemento <application> del file manifest.

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

     Specifica la risorsa XML di Ad Services 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 di Ad Services e sul controllo dell'accesso dell'SDK.

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

3. Registra la tua tecnologia pubblicitaria con Privacy Sandbox per chiamare l'API Topics nel tuo SDK. Per i test in locale, puoi disabilitare il controllo della registrazione a Topics con i seguenti comandi:

   adb shell setprop debug.adservices.disable_topics_enrollment_check true
   

4. Attiva l'accesso all'API Topics. Per impostazione predefinita, l'API Topics è disabilitata. Devi attivarlo utilizzando i comandi ADB:

   adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"

   adb shell setprop debug.adservices.disable_topics_enrollment_check true

5. Per iniziare l'implementazione, esegui il fork della versione Java o Kotlin dell'app di esempio per acquisire familiarità con il recupero degli argomenti su un dispositivo.

Richiedere un insieme di argomenti

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

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

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 necessarie per ricevere dati sugli argomenti. Informazioni necessarie per GetTopicsRequest tessere per recuperare i dati dell'API Topics, incluso un flag per indicare se il chiamante è agire o meno come osservatore. Quando non agisci da osservatore, La chiamata getTopics restituisce un argomento del periodo precedente, ma non influenzano i dati degli argomenti per quello seguente. La OutcomeReceiver gestisce il risultato in modo asincrono. Ad esempio:

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")
    }
}

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");
    }
};

Quando la configurazione è pronta, puoi effettuare una chiamata per ricevere una GetTopicsResponse in base al metodo getTopics():

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

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

Questa chiamata fornirà un elenco di oggetti Topics contenenti valori ID che corrispondono agli argomenti della tassonomia open source pertinenti per l' utente o un errore pertinente. Gli argomenti saranno simili a questo esempio:

/Internet & Telecom/Text & Instant Messaging

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

Test

L'API Topics fornisce argomenti pertinenti e aggiornati in base all'utilizzo delle app. Questa versione preliminare offre un'anteprima dei comportamenti dell'API e miglioreremo la qualità degli argomenti nelle release future.

Per un'esperienza completa, ti consigliamo un ambiente di test con più app in cui chiamare getTopics() per vedere come vengono selezionati gli argomenti. La Repository di API per la tutela della privacy e runtime SDK su GitHub contiene un insieme di singoli progetti Android Studio per aiutarti inclusi esempi che dimostrano come inizializzare e chiamare l'API Topics.

Il calcolo degli argomenti avviene alla fine di un'epoca. Per impostazione predefinita, ogni 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 dell'epoca, esegui il seguente comando:

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

Oltre a utilizzare l'app di esempio, c'è una Colab che che puoi usare per testare diverse combinazioni di informazioni sull'app e confrontarle con gli argomenti classificatore. Utilizza questo colab per visualizzare i tipi di risultati che la tua app è più probabile che ottenga quando chiama getTopics.

Dettagli della crittografia

Con l'introduzione della crittografia, le chiamate a GetTopics() genereranno un con un elenco di oggetti EncryptedTopic. La decriptazione di questi risultati restituiscono un oggetto con lo stesso formato JSON dell'oggetto Topic precedente.

L'API Topics supporta l'implementazione one shot di HPKE (Hybrid Public Key) la crittografia). Ci aspettiamo che l'utente che ha eseguito la registrazione ospiti una chiave pubblica a 32 bit sull'endpoint URL di crittografia pubblica fornito durante la registrazione. Queste chiavi sono dovrebbe essere codificata in Base64.

L'oggetto EncryptedTopic ha 3 campi. L'elenco degli argomenti restituiti può essere ottenuto utilizzando la chiave privata corrispondente per la chiave pubblica.

A scopo di sviluppo, puoi testare la crittografia dell'API Topics disabilitando la verifica di registrazione. In questo modo, l'API verrà forzata a utilizzare la chiave pubblica di test per criptare le risposte. Puoi decriptare gli argomenti criptati utilizzando e la chiave privata corrispondente.

Limitazioni

Per un elenco delle funzionalità in corso per l'API Topics, fai riferimento alle note di rilascio.

Segnalare bug e problemi

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

Passaggi successivi

Vedi anche

Consulta le nostre risorse per comprendere meglio l'API Topics su Android.

• Guarda i video di app di esempio, collaborazioni e procedure dettagliate di Topics.
• Scopri in che modo utenti e sviluppatori possono controllare l'API.
• Consulta le risorse di assistenza per porre domande, partecipare e condividere feedback.