SDK Çalışma Zamanı'nda uyumlulaştırma desteği

Uyumlulaştırma, satıcı tarafı reklam platformlarının gelir yönetimi sunmasının yaygın bir yoludur. Uyumlulaştırma iş akışında, uyumlulaştırma SDK'sı ("arabulucu"), belirli bir slot için en iyi reklamı almak üzere birden fazla reklam ağını ("arabulucu" veya "arabulucu ağı") çağırır. Bazı durumlarda, hem arabulucu hem de çağırdığı reklam ağlarının SDK'larının cihazda bulunması ve etkileşim kurması gerekir.

Bu belgede, SDK çalışma zamanındaki uyumlulaştırma iş akışlarında yapılan önemli değişiklikler özetlenmiştir. Aşağıdaki konular ele alınmıştır:

• Önceki uyumlulaştırma akışları ile mevcut SDK çalışma zamanı uyumlulaştırma desteği arasındaki farklar
• SDK çalışma zamanında uyumlulaştırma iş akışları ve geçişin farklı aşamaları için işlemler ayarlama
• Tüm SDK'ların çalışma zamanına taşınmadığı senaryoların nasıl ele alınacağıyla ilgili kılavuz

SDK Çalışma Zamanı'nda aracılı reklamlar için destek, AGP 8.5 ve SDK Çalışma Zamanı Jetpack kitaplıklarının aşağıdaki sürümlerinde kullanılabilir:

Androidx kitaplığı	Sürüm
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

Sözlük

Aşağıdaki terimler, SDK çalışma zamanındaki uyumlulaştırmayı anlamanın anahtarıdır:

• Çalışma zamanı etkin SDK (RE SDK): SDK çalışma zamanı ortamında çalışacak ve işlemler arası iletişim (IPC) üzerinden uygulamayla iletişim kuracak şekilde tasarlanmış bir SDK.
• Çalışma zamanı bilinçli SDK (RA SDK): Uygulamaya statik olarak bağlı, çalışma zamanında etkinleştirilmemiş bir SDK. Mevcut SDK'nızın yanı sıra çalışma zamanında etkinleştirilen SDK'nızda çağırılacak yeni kod içerebilir.
• Uygulama içi SDK: Uygulamaya statik olarak bağlı olarak çalışan ve SDK Çalışma Zamanı'ndan haberdar olmayan bir SDK. Bu, SDK çalışma zamanına geçiş yapmayan bir reklam ağı veya yayıncının özel bağdaştırıcısı olabilir.
• Uyumlulaştırma aracısı: Diğer reklam ağı SDK'larıyla etkileşime geçerek cihaz üzerinde uyumlulaştırma hizmeti sağlayan reklam uyumlulaştırması SDK'sı.
• Mediatee: Reklam sağlamak ve oluşturmak için Mediator tarafından çağrılan reklam ağı SDK'sı.
• Uyumlulaştırıcı Bağdaştırıcısı: Çeşitli uyumlulaştırılan SDK'larla birlikte çalışabilmek için API arayüzü çevirisi sağlamak amacıyla uyumlulaştırıcı SDK tarafından kullanılan SDK'lar (genellikle uyumlulaştırıcı tarafından sağlanır). Bunlar çalışma zamanından haberdar veya çalışma zamanından habersiz olabilir.

Tipik uyumlulaştırma akışları

SDK'nızın SDK çalışma zamanında uyumlulaştırma kullanım alanlarını desteklemesi gerekiyorsa bazı değişiklikler uygulamanız gerekir. Bu bölümde, arabulucu ve arabuluculuk talep eden taraflar için gerekli değişiklikleri ele alabilmemiz amacıyla arabuluculuk akışlarının temel unsurları incelenmektedir.

Açıkladığımız akışlar, birden fazla reklam ağı SDK'sı içeren cihaz üzerinde uyumlulaştırmanın basitleştirilmiş bir sürümünü temsil eder ve uyumlulaştırma yolculuklarını SDK Çalışma Zamanı ile uyumlu hale getirmek için gereken değişikliklerle ilgili tartışmalara temel oluşturur.

Uyumlulaştırma akışı uygulamalarında görülen çeşitlilik nedeniyle aşağıdaki iki ana akışa odaklanıyoruz:

• Başlatma (reklam ağlarının bulunması ve iletişim dahil)
• Reklam kullanıcı arayüzü (UI) sunumu

Başlatma

Aşağıda standart bir başlatma, reklam ağı keşfi ve iletişim akışı gösterilmektedir:

1. İstemci uygulaması arabulucuyu başlatır
2. Uyumlulaştırma aracısı, ilgili uyumlulaştırılanları ve bağdaştırıcıları bulup başlatır.
3. Uyumlulaştırma aracısı, her uyumlulaştırmayla iletişim kurmak için bağdaştırıcılarını kullanır.
4. İstemci uygulaması, uyumlulaştırma aracısından reklam yüklemesini ister
5. İstemci uygulama, arabulucudan bu reklamı göstermesini ister

Not: Bu akışta, istemci uygulamasının uyumlulaştırma aracısı SDK'sına, uyumlulaştırılan öğelerin SDK'larına ve uyumlulaştırma bağdaştırıcılarına bağımlı olduğu ve bunlarla birlikte oluşturulduğu varsayılır.

Reklam kullanıcı arayüzü sunumu

Önceki adımdaki son istekten sonra reklamın oluşturulması söz konusu olduğunda akış, reklamın türüne bağlıdır:

Banner reklamlar	Tam ekran reklamlar	Yerel reklamlar
Uyumlulaştırma SDK'sı, kazanan uyumlulaştırma aracısının reklam görüntülemesini sarmalayan bir reklam görüntüleme oluşturur. Ayrıca bu görünümde dinleyiciler ayarlayabilir veya reklamı otomatik olarak yenileyebilir (aynı veya farklı bir aracı kullanarak).	Uyumlulaştırma SDK'sı, uyumlulaştırılan öğeden tam ekran reklam ister. Bu da bir etkinlik başlatır.	Yayıncı, arabulucu SDK'sı tarafından döndürülen bileşenleri kullanarak görüntüleme işlemeyi ve şişirmeyi yönetir.

SDK Çalışma Zamanı'ndaki uyumlulaştırıcı akışlar

Uyumlulaştırmanın SDK çalışma zamanında işleyiş şekli, uyumlulaştırılan öğenin çalışma zamanında etkin olup olmamasına bağlı olarak değişir. Buna bağlı olarak aşağıdaki senaryolar söz konusu olabilir:

• Hem arabulucu hem de arabuluculuğa tabi olan taraf SDK Çalışma Zamanı'ndadır: RE mediatee
• Ara aracı, SDK çalışma zamanında, aracı olunan ise uygulama içindedir: Uygulama içi aracı olunan

RE Mediatee

Aşağıdaki mimari şemasında, arabulucunun çalışma zamanında etkinleştirilen (RE) ve çalışma zamanından haberdar olan (RA) SDK'larının, RE uyumlulaştırıcılarının ve arabulucuların RE SDK'larının etkileşimine üst düzey bir genel bakış gösterilmektedir.

Uyumlulaştırma bağdaştırıcıların, arayüz oluşturdukları uyumlulaştırma aracıyla aynı süreçte olması gerekir. Bu nedenle, SDK çalışma zamanına da taşınmaları gerekir.

Şekil 1. Hem uyumlulaştırıcı hem de uyumlulaştırılan RE SDK'larıdır.

Başlatma

Hem çalışma zamanında etkinleştirilen arabulucu hem de arabulucunun başlatılması, bulunması ve iletişimi göz önüne alındığında akış şu adımları uygular:

1. Uygulama (veya RA SDK'sı), SdkSandboxManager#loadSdk kullanarak arabulucu SDK'sını yükler ve başlatır.
2. Ara aracı SDK'sı, başlatma sırasında SdkSandboxController#loadSdk kullanarak SDK Çalışma Zamanı'nda gerekli tüm aracıları yükler ve başlatır.
3. RE SDK, SdkSandboxController#getSandboxedSdks çağrısını yaparak çalışma zamanındaki tüm yüklü SDK'ları keşfedebilir.

Şekil 2. RE arabulucusunu başlatmak için akış.

Not: Çalışma zamanında etkinleştirilen SDK'nızın geriye dönük uyumlu olmasını sağlamak için *Compat çalışma zamanı yöneticisi ve denetleyici sınıflarını kullanın.

Reklam kullanıcı arayüzü sunumu

Aşağıdaki bölümde, RE medya öğesinden banner'ların ve tam ekran reklamların yüklenmesi ele alınmaktadır.

RE Mediatee banner reklamları

Uygulamadan banner reklam yükleme isteği geldiğinde oluşturma işlemini tamamlama akışı aşağıdaki gibidir:

1. Arabulucu, bu reklam için kazanan aracıyı seçer.
2. Arabulucu, arabuluculuk yapılan kişiden SandboxedUiAdapter alır.
3. Arabulucu, UiAdapter'ı uygulamaya yönlendirir.

Şekil 3. Bir RE uyumlulaştırma aracından banner reklam oluşturma işlemini tamamlama akışı.

SandboxedUiAdapter ve SDK Runtime UI Library'nin kullanımı hakkında daha fazla bilgi edinin.

Banner reklamlara yer paylaşımları

Aracılar reklama yer paylaşımı eklemek istiyorsa akışı aşağıdaki şekilde değiştirmeleri gerekir:

1. Arabulucu, yer paylaşımı ve SandboxedSdkView içeren bir düzen oluşturur.
2. Arabulucu, bu reklam için kazanan aracıyı seçer.
3. Arabulucu, arabuluculuk yapılan kişiden SandboxedUiAdapter alır.
4. Arabulucu, arabuluculuğa tabi olan tarafın UiAdapter değerini SandboxedSdkView olarak ayarlar.
5. Arabulucu, doldurulan görünümü uygulamayla paylaşır.

RE Mediatee'den alınan bir banner reklamın üzerine görüntü yerleştirmek için kullanılan akış.

RE Mediatee tam ekran reklamları

Uygulamadan tam ekran reklam yükleme isteği geldiğinde akış şu adımları izler:

1. Uygulama (veya RA SDK'sı), arabulucuya reklam yükleme isteği içeren bir SdkActivityLauncher gönderir.
   1. İstemci, bir önerme kullanarak etkinlik oluşturmayı kısıtlayabilir.
2. Arabulucu, bu reklam için kazanan aracıyı seçer.
3. Uyumlulaştırıcı, uygulamadan SdkActivityLauncher ileterek uyumlulaştırılan öğeden reklam yüklemesini ister.
4. Ara aracı, bir etkinlik işleyici kaydeder ve kayıtlı etkinlik için bir tanımlayıcı jetonu alır.
5. Ara aracı, bu jetonu kullanarak etkinlik başlatma isteğinde bulunmak için SdkActivityLauncher değerini kullanır.
6. İstemci uygulamasının öncülü izin veriyorsa SDK Çalışma Zamanı bu etkinliği özel işlemde başlatır.

Şekil 4. RE Mediatee'den uyumlulaştırılmış tam ekran reklamın nasıl yükleneceğini gösteren akış şeması.

Not: Etkinlik işleyiciyi kaydederken kullandığı ActivityHolder öğesini kullanarak tüm etkinlik yaşam döngüsü etkinliklerine aracı erişebilir.

SDK Çalışma zamanında tam ekran reklamlar için etkinlik desteği hakkında daha fazla bilgi edinin.

Uygulama içi Mediatee

Aşağıdaki mimari şemasında, arabulucunun RE ve RA SDK'larının, SDK çalışma zamanını bilmeyen uyumlulaştırma bağdaştırıcıların ve arabulucuların uygulamaya statik olarak bağlı SDK'larının (çalışma zamanını bilmeyen) etkileşimine genel bir bakış gösterilmektedir.

Şekil 5. Ara aracı, RE SDK'sından haberdar olsa bile uygulamaya statik olarak bağlıdır.

Başlatma

Bu senaryoda uyumlulaştırılanlar uygulamaya statik olarak bağlı olduğundan ve henüz SDK Çalışma Zamanı'na taşınmadığından, uyumlulaştırıcının çalışma zamanında etkinleştirilen SDK'sında bunları kaydedecek bir işlem olmalıdır.

Bu kayda, arabulucunun API'si kullanılarak erişilebilir olmalıdır ancak uygulama ayrıntıları her arabulucunun takdirine bırakılmıştır. Bu API'ye MediationSandboxedSdk#registerInAppMediatee diyoruz.

RE arabulucu SDK'sının ve uygulama içi arabulucu SDK'larının başlatılması, bulunması ve iletişimi söz konusu olduğunda akış şu adımları izler:

1. Uygulama, arabulucunun çalışma zamanından haberdar SDK'sını yükler ve başlatır.
2. Arabulucunun RA SDK'sı:
   1. SdkSandboxManager#loadSdk kullanarak arabulucunun RE SDK'sını başlatır.
   2. Tüm uygulama içi aracı SDK'larını başlatır.
   3. RE SDK'sı (MediationSandboxedSdk#registerInAppMediate) tarafından sağlanan API'yi kullanarak uygulama içi aracı SDK'larını bulur ve kaydeder.

Ara aracının RE SDK'sı, tüm uygulama içi aracı SDK'larının kayıtlı olmasının yanı sıra SdkSandboxController#getSandboxedSdks kullanarak SDK Çalışma Zamanı'na yüklenen tüm SDK'ları keşfedebilir.

Şekil 6. Uygulama içi aracılara referansı kaydetmek için önerilen aracının API'sini kullandığımızı unutmayın.

Reklam kullanıcı arayüzü sunumu

Aşağıdaki bölümde, uygulama içi medya öğesinden banner ve tam ekran reklam yükleme işlemleri ele alınmaktadır.

Uygulama içi aracı banner reklamları

Uygulamadan banner reklam yükleme isteği geldiğinde oluşturma işlemini tamamlama akışı aşağıdaki gibidir:

1. Uyumlulaştırma aracısının çalışma zamanından haberdar olan SDK'sı, uygulamanın isteğini çalışma zamanında etkin olan SDK'sına yönlendirir.
2. Uyumlulaştırma aracısının RE SDK'sı ilgili uyumlulaştırma aracısını seçer.
3. Uyumlulaştırma aracısının RE SDK'sı, uyumlulaştırılan öğeye ait referansı alır ve RA SDK'sı aracılığıyla bir reklam yükleme isteğinde bulunur.
4. RA SDK'sı, uygulama içi uyumlulaştırılan öğeden bir görüntüleme alır.
5. RA SDK'sı, aldığı Görüntü için bir SandboxedUiAdapter oluşturur.
6. RA SDK'sı, UiAdapter öğesini RE SDK'sına yönlendirir.
7. RE SDK'sı, UiAdapter öğesini uygulamaya yönlendirir.

Dikkat: Bu SandboxedUiAdapter, uygulamanın sürecinden alındığından gecikme, performans ve davranış sorunlarına yol açabileceği için bu Görünüm'e yer paylaşımı eklemenizi önermeyiz.

Şekil 7. Arabulucu, uygulama içi aracıdan aldığı görüntülemeleri V1'in üzerine yerleştirmemelidir.

Uygulama içi aracı tam ekran reklamlar

Uygulamadan tam ekran reklam yükleme isteği geldiğinde akış şu adımları izler:

1. Uygulama, bir reklam yükleme isteğiyle birlikte SdkActivityLauncher uyumlulaştırma aracısının RA SDK'sına bir ileti gönderir.
   1. İstemci, bir önerme kullanarak etkinlik oluşturmayı kısıtlayabilir.
2. Uyumlulaştırma aracısının RA SDK'sı, uygulamanın isteğini RE SDK'sına yönlendirir.
3. Uyumlulaştırma aracısının RE SDK'sı:
   1. İlgili arabulucuyu seçer.
   2. Uygulama içi aracıya ait referansı alır.
   3. RA SDK'sı üzerinden reklam yükleme isteklerini gönderir.
4. RA SDK'sı, uyumlulaştırma aracısından bir reklam yüklemesini ister.
5. Aradaki kişi etkinliği doğrudan başlatır. Uygulamanın öncülü dikkate alınmaz.

Şekil 8. Önerme, uygulama içi aracı tarafından yoksayılır.

Not: Etkinlikle ilgili tüm etkinlikler, SDK Çalışma Zamanı'ndan önceki gibi aracı tarafından kullanılabilir.

Etkileşim kurma ve geri bildirim paylaşma

Android'de Özel Korumalı Alan devam eden bir projedir ve bu doküman, mevcut tasarımını yansıtır. Özelliklerini geliştirmeye ve iyileştirmeye devam ederken geri bildiriminiz bizim için çok önemli. Geri bildirimde bulunmak için hata bildirin.