Android'de Topics API'yi uygulama

bookmark_border Koleksiyonlar ile düzeninizi koruyun İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.

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. En güncel özelliklerden yararlanmak için Android Özel Korumalı Alan SDK'sının son sürümünü kullanın sürümlerinden biridir.

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 başvurulan Reklam Hizmetleri XML kaynağını belirtin. Örneğin, res/xml/ad_services_config.xml 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 aşağıdaki komutları kullanarak Topics kayıt 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. 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 isteğinde bulunma

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

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

public void getTopics (@NonNull GetTopicsRequest getTopicsRequest,
    @NonNull Executor executor,
    @NonNull OutcomeReceiver<GetTopicsResponse, Exception> callback)

Bu yöntemi kullanmak için TopicsManager nesnesini ve parametreleri başlatın. gereken tüm bilgileri içerir. GetTopicsRequest, arayanın gözlemci olarak hareket edip etmeyeceğinin belirtildiği bir işaret de dahil olmak üzere Topics API verilerini almak için gerekli bilgileri iletir. Gözlemci olmadığında getTopics çağrısı, önceki dönemden bir konuyu döndürüyor, ancak bunu yapmıyor konu verilerini etkileyebilir. İlgili içeriği oluşturmak için kullanılan OutcomeReceiver geri çağırma, sonucu eşzamansız olarak işler. Örneğin:

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

Kurulum hazır olduğunda, Google Etiket Yöneticisi GetTopicsResponse Sonuç olarak, getTopics() yöntemi:

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

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

Bu çağrı, kimlik değerleri içeren Topics nesnelerinin listesini sağlar açık kaynak sınıflandırmasında, konuyla alakalı veya alakalı bir hata olabilir. 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, test ortamında birden fazla konuların nasıl seçildiğini görmek için getTopics() adlı uygulamayı çağırın. İlgili içeriği oluşturmak için kullanılan SDK Çalışma Zamanı ve Gizliliği Koruyan API Deposu tek tek Android Studio projelerinden oluşan bir set içerir. Topics API'nin nasıl başlatılacağını ve çağrılacağını gösteren örnekler de dahil olmak üzere başlatıldı.

Konu hesaplaması, bir dönemin sonunda gerçekleşir. Varsayılan olarak 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 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

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 olası sonuç türlerini görüntülemek için bu ortak çalışmayı kullanın getTopics aranıyor.

Ş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 nesnesiyle aynı JSON biçimine sahip bir nesne oluşturur.

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 uç noktasında 32 bitlik bir ortak anahtar barındırması gerekir. Bu anahtarların Base64 kodlu olması beklenir.

EncryptedTopic nesnesinin 3 alanı var. Döndürülen konuların listesi, 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 işlem, API'yi test ortak anahtarını şifrelemeyi deneyin. İlgili özel anahtarı kullanarak şifrelenmiş konuların şifresini çözebilirsiniz.

Sınırlamalar

Topics API ile ilgili devam eden özelliklerin listesi için şu sayfaya bakın: sürüm notları gibidir.

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 önerilerinizi bize bildirin.

Sonraki adımlar 'nı inceleyin.

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

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

• Topics'taki örnek uygulamalara, ortak çalışmalara ve açıklamalı videolara göz atın.
• Kullanıcıların ve geliştiricilerin API'yi nasıl kontrol edebileceğini öğrenin.
• Soru sormak, etkileşim kurmak ve geri bildirim paylaşmak için destek kaynaklarına göz atın.