Topics API geliştirici kılavuzu

Android'de Özel Korumalı Alan dokümanlarını okurken, çalıştığınız program sürümünü seçmek için Geliştirici Önizlemesi veya Beta düğmesini kullanın (talimatlar farklı olabilir).

Geri bildirim gönderin

Topics API, bir kullanıcının uygulama kullanımına dayanarak cihaz üzerindeki genel ilgi sinyallerine dair çıkarımda bulunur. Konular adı verilen bu sinyaller, uygulamalarda tek tek kullanıcıları izlemeden ilgi alanına dayalı reklamcılığı desteklemek için reklamverenlerle paylaşılır. Tasarım teklifinde Topics API hakkında daha fazla bilgi edinebilirsiniz.

Önemli: Talimatlar farklılık gösterebileceğinden, çalıştığınız program sürümünü seçmek için SDK Uzantıları Sürümü veya Geliştirici Önizlemesi düğmesini seçin.

Kurulum

Gizliliği koruyan API'lerin en güncel sürümünü edinmek için en yeni Android Özel Korumalı Alan SDK'sını kullanın. Uygulamanızın Topics API'yi kullanması için bir izin eklemeniz ve manifest dosyanıza bir Reklam Hizmetleri yapılandırması oluşturmanız gerekir:

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

Manifest dosyanızın <application> öğesinde bir Reklam Hizmetleri yapılandırmasına referans verin:

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

Manifest'te referans verilen Ad Services XML kaynağını belirtin (ör. res/xml/ad_services_config.xml). Tüm SDK'lara erişim izni vermek için allowAllToAccess özelliğini veya bağımsız SDK'lara erişim izni vermek için allowSdksToAccess özelliğini kullanın. Reklam Hizmetleri izinleri ve SDK erişim denetimi hakkında daha fazla bilgi

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

Ayrıca, bu adb komutlarıyla Topics API'ye erişimi etkinleştirmeniz (varsayılan olarak devre dışıdır) gerekir.

adb shell device_config put adservices ppapi_app_signature_allow_list \"*\"

adb shell setprop debug.adservices.disable_topics_enrollment_check true

Topics API'nin birincil işlevi, aşağıdaki örnekte gösterildiği gibi TopicsManager nesnesinin içindeki getTopics() yönteminde bulunur:

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)

Bu yöntemi kullanmak için TopicsManager nesnesini ve konu verilerini almak için gerekli parametreleri başlatın. GetTopicsRequest, çağrı yapanın gözlemci olarak hareket edip etmeyeceğini belirten bir işaret de dahil olmak üzere Topics API verilerini almak için gerekli bilgileri iletir. Gözlemci görevi olmadığında getTopics çağrısı, önceki dönemdeki bir konuyu döndürür ancak sonraki dönemin konu verilerini etkilemez. OutcomeReceiver geri çağırması, sonucu eşzamansız olarak işler. Örneğin:

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

    }
};

Bir konu grubu isteyin

Kurulumunuz hazır olduğunda getTopics() yönteminin sonucunda, GetTopicsResponse almak için arama yapabilirsiniz:

Kotlin 

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

Java 

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

Yukarıdaki çağrıda, açık kaynak sınıflandırmasında kullanıcıyla alakalı olan konulara veya ilgili bir hataya karşılık gelen kimlik değerlerini içeren Topics nesnelerinin bir listesi sunulur. Konular şu örnektekine benzeyecektir:

/Internet & Telecom/Text & Instant Messaging

Döndürülebilecek olası konuların listesi için sınıflandırmaya bakın. Bu sınıflandırma açık kaynaktır ve önerilen değişiklikler bu sayfanın üst kısmındaki geri bildirim düğmesi kullanılarak gönderilebilir.

Test

Topics API, uygulama kullanımına dayalı alakalı ve yeni konular sunar. Bu erken sürüm, API davranışlarının bir önizlemesini sunar ve gelecekteki sürümlerde konuların kalitesini artıracağız.

En iyi deneyim için, konuların nasıl seçildiğini görmek üzere getTopics() yöntemini çağırdığınız birden fazla uygulama içeren bir test ortamı öneririz. GitHub'daki SDK Çalışma Zamanı ve Gizliliği Koruma API'leri Deposu, başlamanıza yardımcı olacak bir dizi bağımsız Android Studio projesi içerir. Bunlar arasında Topics API'nin nasıl başlatılacağını ve çağrılacağını gösteren örnekler yer alır.

Konu hesaplaması bir "dönemin" sonunda yapılır. Varsayılan olarak her dönem 7 gün sürer ancak sonuç almak için bu aralığı değiştirebilirsiniz. Bu Android Debug Bridge kabuk komutu, dönem uzunluğunu 5 dakikaya kısaltır:

adb shell setprop debug.adservices.topics_epoch_job_period_ms 300000

topics_epoch_job_period_ms değerini getprop ile onaylayabilirsiniz:

adb shell getprop debug.adservices.topics_epoch_job_period_ms

Dönem hesaplamasını manuel olarak tetiklemek için aşağıdaki komutu yürütün:

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

Örnek uygulamayı kullanmanın yanı sıra, farklı uygulama bilgisi kombinasyonlarını konu sınıflandırıcıyla karşılaştırarak test etmek için kullanabileceğiniz bir ortak laboratuvar da vardır. getTopics çağırırken uygulamanızın alabileceği sonuç türlerini görmek için bu colab'i kullanın.

Sınırlamalar

Topics API için geliştirilmekte olan özelliklerin listesi için sürüm notlarına bakın.

Hataları ve sorunları bildirme

Geri bildirimleriniz, Android'de Özel Korumalı Alan için çok önemlidir. Karşılaştığınız sorunları veya Android'de Özel Korumalı Alan'ın iyileştirilmesiyle ilgili fikirlerinizi bize bildirebilirsiniz.