Android'de Topics API'yi uygulama

Kurulum

Topics API'yi uygulamak için önce geliştirme ortamınızı ayarlamanız gerekir. Aşağıdaki kurulum adımlarını uygulayın:

  1. Gizliliği korumaya yönelik API'lerin en güncel sürümünü almak için en son Android Privacy Sandbox SDK'sını kullanın.

  2. Manifest dosyanıza aşağıdakileri ekleyin:

    • İzin: Uygulamanızın Topics API'ye erişmesine izin vermek için ACCESS_ADSERVICES_TOPICS iznini ekleyin:

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

    • Reklam Hizmetleri Yapılandırması: Manifestinizin <application> öğesinde bir Ad Services yapılandırma dosyası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ı (ör. res/xml/ad_services_config.xml) belirtin. Tüm SDK'lara erişim vermek için allowAllToAccess özelliğini, ayrı SDK'lara erişim vermek için allowSdksToAccess özelliğini kullanın. Reklam Hizmetleri izinleri ve SDK erişim denetimi hakkında daha fazla bilgi edinin.

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

  3. SDK'nızda Topics API'yi çağırmak için reklam teknolojinizi Özel Korumalı Alan'a kaydedin. Yerel olarak test etmek için Topics kayıt kontrolünü aşağıdaki komutlarla devre dışı bırakabilirsiniz:

    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  4. Topics API'ye erişimi etkinleştirin. Topics API varsayılan olarak devre dışıdır. ADB komutlarını kullanarak etkinleştirmeniz gerekir:

    adb shell device_config put adservices ppapi_app_signature_allow_list \"\*\"
    adb shell setprop debug.adservices.disable_topics_enrollment_check true

  5. Bir cihazda konuları nasıl alacağınızı öğrenmek için örnek uygulamanın Java veya Kotlin sürümünü forking yaparak uygulamanızı başlatın.

Konu grubu isteme

Topics API'nin birincil işlevi, bu ö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. Bu bilgiler arasında, arayanın gözlemci olarak hareket edip etmeyeceğinin belirtildiği bir işaret de bulunur. Gözlemci olarak hareket etmediğinde getTopics çağrısı, önceki çağdan bir konu döndürür ancak sonraki çağa ait konu verilerini etkilemez. OutcomeReceiver geri çağırma işlevi, 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");
    }
};

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

Bu çağrı, açık kaynak taksonomi'deki kullanıcıyla alakalı konulara karşılık gelen kimlik değerlerini veya alakalı bir hatayı içeren Topics nesnelerinin bir listesini sağlar. Konular aşağıdaki örneğe benzer:

/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 göre alakalı ve güncel konular sağlar. Bu erken sürüm, API davranışlarının bir önizlemesini sunar. Gelecek sürümlerde konuların kalitesini artıracağız.

En iyi deneyimi yaşamak için birden fazla uygulama içeren bir test ortamı kullanmanızı ve konuların nasıl seçildiğini görmek için getTopics() işlevini çağırmanızı öneririz. GitHub'daki SDK Çalışma Zamanı ve Gizliliği Koruma API'leri Deposu, Topics API'nin nasıl başlatılacağını ve çağrılacağını gösteren örnekler de dahil olmak üzere, çalışmaya başlamanıza yardımcı olacak bir dizi bağımsız Android Studio projesi içerir.

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

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

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, uygulama bilgilerinin farklı kombinasyonlarını konu sınıflandırıcısına karşı test etmek için kullanabileceğiniz bir Colab da vardır. Uygulamanızın getTopics araması yaptığında büyük olasılıkla alacağı sonuç türlerini görüntülemek için bu colab'ı kullanın.

Şifreleme ayrıntıları

Şifreleme özelliğinin kullanıma sunulmasıyla birlikte, GetTopics() çağrıları artık EncryptedTopic nesnelerinin listesini içeren bir yanıt oluşturacak. Bu sonuçların şifresi çözüldüğünde, önceki Topic nesnesi ile aynı JSON biçimine sahip bir nesne elde edilir.

Topics API, HPKE'nin (Karma Ortak Anahtar Şifreleme) tek seferlik uygulanmasını destekler. Kayıtlı arayanın, kayıt sırasında sağlanan herkese açık şifreleme URL'si uç noktasında 32 bitlik bir ortak anahtar barındırması gerekir. Bu anahtarların Base64 kodlu olması beklenir.

EncryptedTopic nesnesinin üç alanı vardır. Döndürülen konuların listesi, herkese açık anahtar için ilgili özel anahtar kullanılarak elde edilebilir.

Geliştirme amacıyla, kayıt kontrolünü devre dışı bırakarak Topics API şifrelemesini test edebilirsiniz. Bu, API'yi yanıtlarınızı şifrelemek için test ortak anahtarını kullanmaya zorlar. İlgili özel anahtarı kullanarak şifrelenmiş konuların şifresini çözebilirsiniz.

Sınırlamalar

Topics API için geliştirilmekte olan özelliklerin listesini sürüm notlarında bulabilirsiniz.

Hataları ve sorunları bildirme

Geri bildiriminiz, Android'de Özel Korumalı Alan'ın önemli bir parçasıdır. Android'de Özel Korumalı Alan'da bulduğunuz sorunları veya iyileştirme fikirlerinizi bize bildirin.

Sonraki adımlar

Kullanıcıların ve geliştiricilerin Topics API'yi nasıl yönetebileceğini ve kullanıcı tercihlerine ve ihtiyaçlarına göre nasıl özelleştirebileceğini öğrenin.
Topics'in Android'de işleyiş şeklini anlayın ve API akışının temel adımları hakkında bilgi edinin.

Aşağıdaki kaynakları da incelemenizi öneririz:

Android'de Topics API'yi daha iyi anlamak için kaynaklarımıza göz atın.