Mobil Cihazlar için Topics API'ye genel bakış

Not: Bu makale, Android'in mevcut tasarım tekliflerini yansıttığından Özel Korumalı Alan'ın üzerinde değişiklik yapılabilir. Geri bildirim ve görüşlerinizi paylaşarak bu çabalara yardımcı olmanızı öneriyoruz.

Geri bildirim gönderin

Topics API hakkında

Mobil reklamcılıkta, reklamverenler kullanıcının ilgi alanıyla alakalı reklamlar sunmak ister. Örneğin, bir kullanıcı yemek pişirmeyle ilgili bilgilerle ilgileniyorsa, ilgi alanlarıyla alakalı olmayan reklamlara kıyasla yemek pişirmeyle ilgili reklamların kendisiyle daha alakalı olduğunu görebilir.

İçeriğe dayalı reklamcılık, yalnızca görüntülenen (ve reklamı yapılan) mevcut içerikten türetilen ilgi alanlarına dayalıdır. Topics API'nin avantajlarından biri de, kullanıcı için faydalı olan ancak içeriğe dayalı reklamcılık yoluyla belki para kazanmak için uygun olmayan uygulamaların, kullanıcıya normalde gösterebileceğinden daha alakalı reklamlar göstermesine olanak tanımasıdır. Bu da, kullanıcının kullandığı uygulamaları finanse etmeye yardımcı olur.

Topics API, bir kullanıcının uygulama kullanımına dayanarak cihaz üzerindeki genel ilgi sinyallerine dair çıkarımda bulunur. "Konu" adı verilen bu sinyaller, reklamverenler ile paylaşılacak. Bu sayede, uygulamalarda her bir kullanıcının takip edilmesine gerek kalmadan birinci taraf ve birinci taraf sinyalleri desteklenecek.

Topics API, genellikle birden fazla uygulamada çalışan üçüncü taraf reklam SDK'larını desteklemek için tasarlanmıştır. Bu destek, söz konusu SDK'ların normalde gözlemleyeceği uygulamalar arası ilgi alanlarından bazılarını gösterme şeklinde sunulur. Her uygulama geliştirici, kullanıcıları hakkında ek bilgi öğrenmeyi beklememelidir.

Temel kavramlar

• Konu, bu kullanıcının okuyabileceği, kullanıcıların okuyabileceği bir konudur ve Topics sınıflandırmasının bir parçasıdır.
• Bir konu, çağrıyı yapan kişi son 3 dönemde bu konuyla ilişkili bir uygulamadan Topics API isteği yapmışsa çağrıyı yapan kişi (uygulamada kullanılan bir uygulama veya üçüncü taraf SDK'sı) tarafından gözlemlenir.
• Dönem, konuların hesaplandığı bir dönemdir (ör. bir hafta).

İşleyiş şekli

Bu teklifle Topics API, arayanlara kullanıcının uygulama kullanımına dayalı olarak genel ilgi alanlarına yönelik reklamcılık konuları sunmayı amaçlar. Bu konular, reklam görüntülemek isteyen uygulamayla ilgili bağlamsal bilgileri tamamlamak için kullanılabilir ve kullanıcı için uygun bir reklam bulmaya yardımcı olmak üzere birleştirilebilir.

İlgi alanına dayalı reklamcılık için konu getirme özelliğinin nasıl ayarlanacağını gösteren kod örnekleri için Topics API geliştirici kılavuzuna bakın. Not: API'ler henüz son halini almamıştır.

Konular önceden tanımlanmış açık kaynaklı bir sınıflandırmadan seçilir.

Platform, konuları belirlemek için bir sınıflandırıcı modeli kullanır. Topics API'nin uygulanması ve sınıflandırıcının kullanımı, Android Açık Kaynak Projesi'nin bir parçası olacak ve zaman içinde gelişecektir.

Aşağıdaki kod örneğinde, açıklama amacıyla ilgi alanına dayalı bir reklam getirmek için konuların kullanımı gösterilmektedir. Burada kullanılan API'ler nihai değildir.

// Initialize the Topics API.
…
topicsFuture = AdvertisingTopicsClient.getTopics();

// Retrieve Topics and use them in Ad request.
Futures.addCallback(
    topicsFuture,
    new FutureCallback<AdvertisingTopicsInfo>() {
        @Override
        public void onSuccess(@Nullable AdvertisingTopicsInfo topicsInfo) {
            // Sanitize Topics result.
            ...
            // Initialize ad request with Topics obtained.
            AdRequest adRequest = AdRequest.initialize(topicsInfo);
        }

        @Override
        public void onFailure(Throwable t) {
            // Handle error.
            ...
        }
});

Sınıflandırıcı modelinin nasıl çalıştığını daha iyi anlamak için Android Topics Sınıflandırıcı Colab'i kullanarak farklı uygulama verilerinin sistemde nasıl tepki verdiğini test edebilirsiniz.

Topics API'lerine erişim elde etme

Topics API'ye erişmek için reklam teknolojisi platformlarının kaydolması gerekir. Daha fazla bilgi için Özel Korumalı Alan hesabına kaydolma bölümüne bakın.

Ayrıntılar

• Her dönemde bir kez (ör. haftada bir) kullanıcının en çok ilgi gösterdiği 5 konu, cihaz üzerindeki bilgiler kullanılarak hesaplanır.

  • Topics API çağrıldığında platform, API'yi çağıran uygulamaya bir konu atanıp atanmadığını kontrol eder. Atanmış konu yoksa aşağıdaki gibi bir konu seçilir ve seçilen konu, bu dönemin geri kalanı için bu uygulamaya atanır.
    • %95 olasılıkla, o dönem için hesaplanan en iyi 5 konu listesinden rastgele bir konu seçilir.
    • %5 olasılıkla, sınıflandırmadan rastgele bir konu seçilir.
    • Bir çağrıyı yapan, shouldRecordObservation = false parametresini kullanıp getTopics yöntemini çağırarak konuları durumu değiştirmeden almak istediğini belirtebilir. Bu, konuların döndürülebileceği anlamına gelir ancak çağrı, haftalık sıfır hesaplamasına dahil edilmez veya arayan için gözlemlenen konuların listesini güncellemez.
  • Her uygulamanın farklı konulardan birini almasının nedeni, farklı uygulamaların farklı konular almasını sağlamaktır. Böylece, uygulamaların aynı kullanıcıyla çapraz bağıntı kurması zordur.
    • Örneğin, A uygulaması kullanıcı için T1 konusunu, B uygulaması ise T2 konusunu görebilir. Bu durum, iki uygulamanın bu bilgilerin aynı kullanıcıyla ilişkilendirildiğini belirlemesini zorlaştırır.

• Topics API, son 3 dönemin her biri için 1 olmak üzere en fazla 3 konu içeren bir liste döndürür.

  • En fazla 3 konu sağlayarak, sık kullanılmayan uygulamalar alakalı reklamları bulmak için yeterli konuya sahip olur. Ancak sık kullanılan uygulamalar haftada en fazla 1 yeni konu öğrenir.
  • Döndürülen konu bilgileri, sınıflandırmadaki bir girişe karşılık gelen konu kimliği (int), sınıflandırma sürümü ve sınıflandırıcı modeli sürümü içerir.
  • Yalnızca son 3 dönem içinde kullanıcının konuyla ilişkili bir uygulamayı kullandığını gözlemleyen arayanlar konuyu alabilir.
  • Döndürülen tüm konular kullanıcının ilgi alanlarını temsil eder. Reklam kişiselleştirme için bu konuların herhangi birini veya tümünü reklam isteğinizde seçebilirsiniz.

• Topics API'yi çağıran uygulamaya bir konu atandıktan sonra platform, çağrıyı yapanın bu konuyu alıp alamayacağını belirler.

  • Yalnızca son 3 dönemde söz konusu konuyla ilişkili uygulama ile ilgili kullanıcı etkileşimini gözlemleyen arayanlar konuyu alabilir.
  • Arayan kişi, geçmişte bu konuyla ilgili bir uygulamada söz konusu kullanıcı için API'yi çağırmadıysa konu, API tarafından döndürülen listeye dahil edilmez.
  • Arayan kişi son 3 dönemde herhangi bir konu almadıysa Topics API boş bir liste döndürür.

  Örneğin, kullanıcının cihazda A, B, C, D, E, F ve G olmak üzere 7 uygulaması yüklü olduğunu varsayalım. Uygulamanın ve bu uygulamalardaki reklam teknolojisi SDK'larının konu sınıflandırmasının aşağıdaki gibi olduğunu varsayalım:

  Uygulama	Konu sınıflandırması	Reklam teknolojisi SDK'sı
  CEVAP	Ş1, Ş5	ad-sdk1, ad-sdk2
  B	T2	ad-sdk2
  C	T3, Ş6	ad-sdk3, ad-sdk4
  D	Ş1, Ş4	reklam-sdk1
  E	T5	ad-sdk4, ad-sdk5
  F	T6	ad-sdk2, ad-sdk3, ad-sdk4
  G	T7	ad-sdk2

  • 1. hafta sonu: Topics API, kullanıcının bu dönem için en popüler 5 konusunu oluşturur.

  En Popüler Konu	Konu hakkında bilgi edinebilen arayanlar
  T1	ad-sdk1, ad-sdk2
  T2	ad-sdk2
  T3	ad-sdk3, ad-sdk4
  T4	reklam-sdk1
  T5	ad-sdk1, ad-sdk2, ad-sdk4, ad-sdk5

  • 2. haftada, herhangi bir uygulamadan gelen bir çağrı API'yi çağırırsa döndürülen konu listesi yalnızca çağrıyı yapan kişinin, o dönem için o uygulamanın konusuyla ilgili "Konu hakkında bilgi alabilen arayanlar" sütununda yer aldığı konuları içerir.
  • Her bir arayanın kullanabileceği konuların hesaplamasına dahil edilen geçmiş aralığı 3 dönemdir (veya 3 hafta).
  • Yalnızca reklam SDK'ları aracılığıyla Topics API'yi çağıran uygulamalarla ilişkili konular kullanılır. Bu, bir uygulama Topics API'yi çağıran herhangi bir reklam SDK'sı içermiyorsa bu uygulamayla ilişkilendirilen konuların, reklam SDK'larının erişebildiği konu havuzuna katkıda bulunmadığı anlamına gelir.
  • Ayrıca bir uygulama, reklam SDK'larının ilgili uygulama için API'yi kullanmasına izin vermemek üzere yeni manifest ve XML öğeleri aracılığıyla Topics API'nin kapsamı dışında kalmayı bildirimli şekilde devre dışı bırakabilir. Devre dışı bırakılan uygulamalarla ilişkili konular, haftalık konu hesaplamasına katkıda bulunmaz. Bu belge, ilgili uygulama ayrıntılarını içerecek şekilde güncellenecektir.

• Platformun 5 konu hakkında sonuç çıkarmasına yetecek kadar uygulama kullanımı yoksa kalan konuları rastgele oluşturma gibi seçenekleri değerlendirebilir.

Sınıflandırma

• Mevcut teklifte ilk sınıflandırma birkaç yüz ila birkaç bin konu içerecektir. İlk sınıflandırma teklifi, bu belgenin daha sonraki bir güncellemesinde paylaşılacaktır.
• Bu sınıflandırma, hassas konuların sınıflandırmaya dahil olmaması için gerçek kişiler tarafından seçilmiş olacaktır.
• Bu sınıflandırma, Android'deki mobil uygulamalarda gösterilebilecek reklam kategorilerine uyarlanacaktır.
• Sınıflandırma herkesin kullanımına açıktır ve değiştirilebilir. Öneriler, bu sayfanın üst kısmındaki geri bildirim düğmesini kullanarak gönderebilirsiniz.

Konu sınıflandırıcı

İlgilendiğiniz konular, herkese açık uygulama bilgilerine (uygulama adı, açıklama ve paket adı gibi) göre eğitilmiş bir sınıflandırıcı modelinden türetilir.

• Sınıflandırıcı modeli, belirli bir sıfırın konularını hesaplamak üzere çıkarım için kullanıldığında, kullanılan sinyal grubu cihazda kalır. Bu sinyal grubu, yüklenen veya yakın zamanda kullanılan uygulamaları içerebilir ve daha sonra diğer sinyalleri içerecek şekilde genişletilebilir.
• İlk modeller Google tarafından eğitilir. Burada eğitim verileri, herkese açık uygulama bilgileri için insanlar tarafından seçilen etiketleri içerir. Uygulamalar, uygulamalarının hangi konulara göre sınıflandırıldığını görmek için bu modele ücretsiz olarak erişebilir.
• İlk modeller, Google Play Store gibi sınırlı sayıda uygulama mağazasından alınan uygulamalarla ilgili herkese açık bilgilere göre eğitilir.
• Bir uygulama 1'den fazla konuyla eşleşebilir veya hiçbir konu ile eşleşmeyebilir ya da kullanıcının konu geçmişine katkıda bulunmayabilir. Bir uygulamanın sınıflandırmada 1'den fazla konuyla eşleşmesi durumunda, bu uygulama için seçilen konuların sayısı ilk 3 ile sınırlı olur.

Kullanıcı denetimleri

• Tasarım, kullanıcıların uygulama kullanımlarıyla ilişkilendirilen konuları görüntüleyebilmelerini ve kaldırabilmelerini amaçlamaktadır. Bu kullanıcı denetimi özelliğinin uygulanması şu anda devam eden bir çalışmadır ve gelecekteki bir güncellemeye dahil edilecektir.
• Kullanıcı son 3 dönemde tahmin edilen bir konunun seçilmesine katkıda bulunan bir uygulamayı kaldırırsa bu konu, kaldırma işlemiyle ilgili bilgilerin ifşa edilmesini önlemek amacıyla son 3 dönem için döndürülen konular listesinden kaldırılmaz.

Son kullanıcı deneyiminin nasıl olacağına yönelik testleri kolaylaştırmak amacıyla, Topics için son kullanıcının gördüğüne benzer ayarlar kullanıcı arayüzünü görüntülemek için bir uygulama içi intent de kullanıma sunabilirsiniz. Bu aramanın bir örneğini aşağıda görebilirsiniz:

//Button that launches settings UI
private Button mSettingsAppButton;
private static final String RB_SETTING_APP_INTENT = "android.adservices.ui.SETTINGS";


//Does setup for button on screen that will launch settings UI to observe Topics
private void registerLaunchSettingsAppButton() {
    mSettingsAppButton.setOnClickListener(
        new View.OnClickListener() {

            @Override
            public void onClick(View view) {
                Context context = getApplicationContext();
                Intent activity2Intent = new Intent(RB_SETTING_APP_INTENT);
                activity2Intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
                context.startActivity(activity2Intent);
            }
        });
}

Bir reklam teknolojisi platformuna kaydolun

Topics API'ye erişmek için tüm reklam teknolojisi platformlarının (Google dahil) kayıt işlemini tamamlaması gerekir.

Uygulama geliştiricileri, uygulama manifest dosyasına reklam teknolojisi geliştiricisinin kayıt kimliğini dahil ederek Topics API'lerine hangi reklam teknolojisi geliştiricilerinin erişebileceğini yönetebilir.

Döndürülen konuların şifrelenmesi

Topics API'yi çağıran kayıtlı reklam teknolojisi platformlarının, döndürülen konuların yalnızca arayan tarafından okunabilmesi için şifreleme anahtarları sağlamaları da gerekir.

Özel Korumalı Alan, bu anahtarları reklam teknolojisi tarafından sağlanan uç noktadan getirir. En iyi uygulama olarak, anahtarların sık sık (en geç 6 ayda bir) güncellenmesini öneririz.

Özel Korumalı Alan, reklam teknisyenlerinden kayıt işlemi sırasında reklam teknolojisi tarafından sağlanan uç noktanın kullanılabilirliğini onaylamalarını ister. Mevcut ve yeni kaydolan reklam teknolojilerinin gerektirdiği işlemler hakkında daha ayrıntılı bilgi için Kayıt Geliştirici Kılavuzu'na göz atın.

Şifreleme ayrıntıları

Şifrelemenin kullanıma sunulmasıyla birlikte, "GetTopics()" çağrıları artık "EncryptedTopic" nesnelerinden oluşan bir listeyle yanıt oluşturacaktır. Bu sonuçların şifresinin çözülmesi, önceki Topic nesnesiyle aynı JSON biçimine sahip bir nesneyle sonuçlanır.

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

EncryptedTopic nesnesinin 3 alanı var. Döndürülen konuların listesine, ortak anahtara karşılık gelen özel anahtar kullanılarak ulaşılabilir.

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