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 koruyan API'lerin en güncel sürümünü edinmek için en yeni 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" />

    • Ad Services Configuration: Manifestinizin <application> öğesinde bir Ad Services Configuration dosyasına referans verin.

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

      Manifest'te referans verilen reklam hizmetleri XML kaynağını belirtin. Örneğin: res/xml/ad_services_config.xml. Tüm SDK'lara erişim izni vermek için allowAllToAccess özelliğini, her SDK'ya ayrı ayrı erişim izni vermek için ise 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 aşağıdaki komutlarla Topics kaydı kontrolünü 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. Cihazdaki konuları nasıl alacağınızı öğrenmek için örnek uygulamanın Java veya Kotlin sürümünü çatallayarak uygulamaya başlayın.

Bir dizi konu isteğinde bulunma

Topics API'nin temel 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 konular verilerini almak için gereken parametreleri başlatın. GetTopicsRequest, arayanı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 olarak davranılmadığında getTopics çağrısı, önceki dönemden bir konu döndürür ancak sonraki dönemdeki konular verilerini etkilemez. The 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 tamamlandıktan sonra getTopics() yöntemiyle GetTopicsResponse sonucu 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ğırma işlemi, açık kaynak taksonomisindeki kullanıcıyla alakalı konulara karşılık gelen kimlik değerlerini içeren bir Konular nesneleri listesi veya alakalı bir hata 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 kaynaklıdı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 sunar. Bu ilk sürümde API davranışlarının önizlemesi sunulmaktadır. Gelecekteki sürümlerde konuların kalitesini artıracağız.

En iyi deneyimi elde etmek için konuların nasıl seçildiğini görmek üzere getTopics() çağrısı yaptığınız birden fazla uygulamanın bulunduğu 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. Bu projeler arasında Topics API'nin nasıl başlatılacağını ve çağrılacağını gösteren örnekler de 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önemin 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ı konular sınıflandırıcısıyla test etmek için kullanabileceğiniz bir Colab da vardır. Uygulamanız getTopics çağrısı yaptığında alabileceği sonuç türlerini görmek için bu Colab'i kullanın.

Şifreleme ayrıntıları

Şifrelemenin kullanıma sunulmasıyla birlikte, GetTopics() ile yapılan aramalar artık EncryptedTopic nesnelerinin listesini içeren bir yanıt oluşturacak. Bu sonuçların şifresinin çözülmesi, önceki Topic nesnesiyle aynı JSON biçimine sahip bir nesneyle sonuçlanır.

Topics API, HPKE'nin (Hibrit Ortak Anahtar Şifreleme) tek seferlik uygulanmasını destekler. Kaydolmuş 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ı beklenir. Bu anahtarların Base64 kodlu olması beklenir.

EncryptedTopic nesnelerinin üç alanı vardır. Döndürülen konuların listesi, ortak anahtar için karşılık gelen ö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'nin yanıtlarınızı şifrelemek için test ortak anahtarını kullanmasını zorlar. Şifrelenmiş konuların şifresini ilgili özel anahtarı kullanarak çözebilirsiniz.

Sınırlamalar

Topics API'de devam eden özelliklerin listesi için sürüm notlarına bakın.

Hata ve sorun bildirme

Geri bildiriminiz, Android'de Özel Korumalı Alan'ın önemli bir parçasıdır. Android'de Özel Korumalı Alan'ı iyileştirmeye yönelik fikirlerinizi veya karşılaştığınız sorunları 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.