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ılık gösterebilir.

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 olarak adlandırılan bu sinyaller, ilgi alanına dayalı reklamcılığı uygulamalarda bireysel kullanıcıları izlemeden 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 manifest dosyanıza bir izin eklemeniz ve Ad Services yapılandırması oluşturmanız gerekir:

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

Manifest'inizin <application> öğesinde bir Ad Services yapılandırmasına referans verin:

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

Manifest'te başvurulan Ad Services XML kaynağını (res/xml/ad_services_config.xml gibi) belirtin. 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, Topics API verilerini almak için gerekli bilgileri iletir. Arayan kişinin gözlemci olarak hareket edip etmeyeceğini belirten bir işaret de yer alır. Gözlemci rolü olmadığında getTopics çağrısı, önceki dönemden bir konu döndürür ancak bir sonraki dönemin konu verilerini etkilemez. OutcomeReceiver geri çağırma, 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 dizi konu isteyin

Kurulumunuz hazır olduğunda getTopics() yönteminin sonucu olarak 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ı, açık kaynak sınıflandırmasında kullanıcıyla alakalı konulara veya ilgili bir hataya karşılık gelen kimlik değerlerini içeren Topics nesnelerinin bir listesini sağlar. 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 kaynaklıdır ve önerilen değişiklikler, bu sayfanın üst kısmındaki geri bildirim düğmesi kullanılarak kaydedilebilir.

Test

Topics API, uygulama kullanımına dayalı alakalı ve yeni konular sağlar. Bu erken sürüm, API davranışlarının bir önizlemesini sunar ve gelecekteki sürümlerde konuların kalitesini artırırız. En iyi deneyim için, konuların nasıl seçildiğini görmek üzere getTopics() numaralı telefonu aradığınız birden fazla uygulamanın bulunduğu bir test ortamı kullanmanızı ö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. Bunlara Topics API'nin nasıl başlatılacağını ve çağrılacağını gösteren örnekler de dahildir.

Konular 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, sıfır zamanı 5 dakikaya indirir:

adb shell device_config put adservices topics_epoch_job_period_ms 300000

topics_epoch_job_period_ms değerini get ile onaylayabilirsiniz:

adb shell device_config get adservices topics_epoch_job_period_ms

Sıfır noktası 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 uygulamanı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 çalışma da vardır. Uygulamanızın getTopics çağırırken alabileceği sonuç türlerini görüntülemek için bu ortak çalışmayı 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'deki Özel Korumalı Alan için çok önemlidir. Android'de Özel Korumalı Alan'ı iyileştirmeyle ilgili bulduğunuz sorunları veya fikirlerinizi bize bildirin.