SDK Çalışma Zamanı kullanıcı arayüzü sunum API'leri

Not: Android'deki Ö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.

SDK Çalışma Zamanı, reklam SDK'larının korumalı bir ortamda çalışmasına olanak tanır ve bu sayede yayıncının görüntüleme hiyerarşisine erişmelerini engeller. Platform, reklam görüntülemek için SDK'ya bir SandboxedSdkProvider.getView API'si sunar ve reklam görüntülemesini alır. Ardından, bu görüntülemeyi istemci uygulamasına IPC (işlemler arası iletişim) üzerinden gönderilecek bir SurfacePackage olarak paketler. Bunun birkaç dezavantajı vardır. Bunlar aşağıda açıklanmıştır. Ardından bu dokümanda, bu zorlukları gidermek için geliştirilmekte olan önerilen bir Jetpack kitaplığı sunulur.

Platform API'lerini geliştirmenin nedeni

Çerçeve API'leri esneklik için tasarlanmıştır ve kullanıcı arayüzü sunumu için yan kanal oluşturma görevini uygulamaya ve SDK'ya bırakır. Bu yan kanal aşağıdakileri yapar:

1. SDK'nın, yaşam döngüsü boyunca birden fazla reklam görüntülemesini yönetmesine ve SDK tarafından oluşturulduktan sonra reklam kullanıcı arayüzüne ne olduğunu anlamasına olanak tanır.
2. Görüntü oluşturma ve içerik bağlama işlemlerini birbirinden ayırır. Yan kanalın kullanılması, SDK'nın uygulamaya reklam isteğine karşılık gelen bir nesne (içerik) döndürmesine olanak tanır. Bu nesne, uygulama uygun gördüğünde reklam kapsayıcısına bağlanabilir.
3. İşlemler genelinde kullanıcı arayüzünü göstermek için kullanılan temel platform yapılarını soyutlar. (Platform şu anda bir SurfaceControlViewhost kullanıyor ve bundan bir SurfacePackage oluşturuyor.)
4. SDK çalışma zamanındaki reklam SDK'larının, reklam kapsayıcının kullanıcı arayüzü değiştiğinde otomatik olarak bildirim almasını sağlar. Bir yayıncı reklam kapsayıcısının düzenini değiştirirse SDK, yayıncı açıkça bir API çağırarak SDK'yı bilgilendirmediği sürece bu değişikliklerden haberdar olmaz.
5. Kullanıcı tarafından görülebilen herhangi bir takılma olmadan reklam kullanıcı arayüzünün ve reklam kapsayıcısının yeniden boyutlandırılmasını senkronize eder.
6. Geriye dönük uyumluluğu otomatik olarak yönetir. SurfacePackage, API düzeyi 30'dan önce kullanılamaz. Ayrıca, SDK çalışma zamanının olmadığı ve SDK'nın yayıncı için yerel işlem olduğu cihazlarda, görüntüleme doğrudan SDK'dan alınabiliyorsa reklam için SurfacePackage oluşturmak israftır. Yan kanal, bu karmaşıklığı SDK ve uygulama geliştirici kodundan soyutlar.
7. Reklam kullanıcı arayüzünün Composables ile sorunsuz şekilde entegre edilmesini sağlar. Görünümlerle çalışmayan Jetpack Compose geliştiricileri, görünümlerle çalışmaya devam eden SDK geliştiricisi tarafından oluşturulan kullanıcı arayüzünü barındırmaya da devam edebilir.

Kullanıcı arayüzü kitaplıkları

Kullanıcı arayüzü kitaplıkları, yukarıda ayrıntılı olarak açıklanan karmaşıklıkları ortadan kaldırır ve yayıncının ve SDK'nın süreçler genelinde kullanıcı arayüzünü göstermek ve kullanıcı arayüzü ile cihazla etkileşimde bulunurken güncel tutmak için kullanabileceği yan kanalı sağlar.

Üç kullanıcı arayüzü kitaplığı vardır: core, client ve provider. Temel kitaplık, istemci ve sağlayıcı kitaplıkları tarafından kullanılan arayüzleri sağlar. Kullanıcı arayüzü sağlayıcısı (genellikle SDK), sağlayıcı kitaplığına, kullanıcı arayüzünün tüketicisi (genellikle yayıncı) ise istemci kitaplığına bağlıdır. İstemci ve sağlayıcı kitaplıkları birlikte, kullanıcı arayüzü oturumu oluşturmak ve sürdürmek için gereken yan kanalı oluşturur.

API'ler

SDK Runtime kullanıcı arayüzü sunumu için API'ler şunlardır:

SandboxedUiAdapter: SDK tarafından oluşturulur ve yayıncının kullanıcı arayüzünde gösterilecek içeriği elde etmenin bir yolunu sağlar.

SandboxedSdkView: Yayıncı tarafından oluşturulan bu kapsayıcı, SandboxedUiAdapter aracılığıyla elde edilen içeriği barındırır.

Session: SandboxedUiAdapter.openSession() isteğine yanıt olarak SDK tarafından oluşturulur. Bir kullanıcı arayüzü oturumunu temsil eder. Bu, SDK ile yayıncı arasındaki iletişim tünelinin SDK ucunu oluşturur ve SandboxedSdkView'teki değişiklikler (ör. pencerenin ayrılması, yeniden boyutlandırma veya yapılandırma değişiklikleri) hakkında bildirim alır.

SessionClient: İstemci kitaplığı tarafından oluşturulan bu yapı, SDK ile yayıncı arasındaki iletişim tünelinin yayıncı tarafını oluşturur.

SandboxedSdkUiSessionStateChangedListener: Yayıncı tarafından oluşturulur. SandboxedSdkView ile ilişkili kullanıcı arayüzü oturumunun durumundaki değişiklikleri dinleyen bir dinleyici.

SDK Runtime kullanıcı arayüzü sunma API'leri arasındaki ilişkiler.

Bu API'ler hakkında daha fazla bilgi için privacysandbox-ui referans dokümanlarını okuyun.

Kontrol akışı

Aşağıdaki şemalarda, çeşitli senaryolarda istemci ile sağlayıcı kullanıcı arayüzü kitaplıkları arasındaki etkileşim gösterilmektedir:

Önceki şemada, yayıncının programlı olarak veya XML'i aracılığıyla bir SandboxedSdkView oluşturabileceği ve bunu SDK'da tanımlanan bir API aracılığıyla SDK'dan alınan bir SdkSandboxUiAdapter'a nasıl ekleyebileceği gösterilmektedir. Kullanıcı arayüzü durumundaki tüm değişiklikleri gözlemlemek için yayıncının SdkSandboxUiAdapter'i eklemeden önce SandboxedSdkView'a bir SandboxedSdkUiSessionStateChangedListener eklemesi gerekir.

SDK'dan kullanıcı arayüzünü alın.

Bu şema, yayıncının etkinliği yapılandırma değişikliklerini ele alırsa istemci kitaplığının yapılandırma değişikliğini SDK'ya iletme işlemini nasıl gerçekleştirdiğini gösterir. Böylece kullanıcı arayüzünü buna göre güncelleyebilirler. Örneğin, bu akış kullanıcı cihazı döndürdüğünde ve yayıncı android:configChanges=["orientation"] ayarını yaparak etkinliğindeki yapılandırma değişikliklerini işlediğini beyan ettiğinde tetiklenebilir.

Yayıncı tarafından başlatılan kullanıcı arayüzü değişikliği.

Bu şema, SDK'nın SessionClient'teki yöntemleri kullanarak reklam kapsayıcısında nasıl değişiklik isteğinde bulunabileceğini gösterir. Bu API, SDK reklamı yeniden boyutlandırmak istediğinde ve yayıncının reklam kapsayıcısını yeni boyutlara uyacak şekilde yeniden boyutlandırması gerektiğinde tetiklenir. Bu durum, kullanıcı etkileşimine yanıt olarak gerçekleşebilir (ör. mraid.resize()).

SDK tarafından başlatılan kullanıcı arayüzü değişikliği.

Bu diyagramda, SandboxedSdkView pencereden kaldırıldığında oturumun nasıl kapatılacağı gösterilmektedir. Oturum, SDK tarafından SessionClient.onSessionError() çağrılarak da herhangi bir zamanda (ör. kullanıcı ağ bağlantısını kaybettiğinde) kapatılabilir.

Kullanıcı arayüzü oturumu kapatılıyor.

Z sırası

İstemci kullanıcı arayüzü kitaplığı, SDK'nın kullanıcı arayüzünü barındırmak için dahili olarak bir SurfaceView kullanır. SurfaceView, kullanıcı arayüzünü yayıncının penceresinin üstünde veya altında göstermek için Z sırasını kullanabilir. Bu, doğru/yanlış setOnTop değerini kabul eden SandboxedSdkView.orderProviderUiAboveClientUi() yöntemi tarafından kontrol edilir.

setOnTop true olduğunda, SandboxedSdkView üzerindeki her android.view.MotionEvent SDK'ya gönderilir. false olduğunda bu veriler yayıncıya gönderilir. Hareket etkinlikleri varsayılan olarak SDK'ya gönderilir.

Yayıncıların genellikle reklam görüntülemelerinin varsayılan Z sırasını değiştirmesi gerekmez. Ancak, bir reklamı kapsayan kullanıcı arayüzü (ör. açılır menü) gösterilirken Z-sıralama geçici olarak varsayılandan tersine çevrilmeli ve kapsayıcı kullanıcı arayüzü öğesi kapatıldığında geri yüklenmelidir. İstemci kullanıcı arayüzü kitaplığında bu süreci otomatikleştirmenin yollarını araştırıyoruz.

Kaydırma

Reklam kullanıcı arayüzü, yayıncı penceresinin Z-üstüne sipariş edildiğinde, reklam kullanıcı arayüzünden SDK'ya MotionEvents gönderilir. Reklam kullanıcı arayüzünde başlatılan kaydırma ve fırlatma hareketleri özel işleme tabi tutulur:

1. Dikey kaydırma ve fırlatma hareketleri, yayıncının kapsayıcısına gönderilir ve bu kapsayıcı tarafından işlenir. Bu, reklam kullanıcı arayüzünün yerleştirildiği yayıncının kapsayıcısının dikey olarak kaydırılabilir olduğunda iyi bir kullanıcı deneyimi sağlar. Bu işlem için SDK veya yayıncı tarafında herhangi bir ek çalışma gerekmez.
2. Yatay kaydırma ve fırlatma hareketleri SDK'ya gönderilir ve SDK tarafından işlenir. Bu, reklam kullanıcı arayüzünün yatay olarak kaydırılabilir olduğu durumlarda (reklam bandı gibi) iyi bir kullanıcı deneyimi sağlar.

Uygulama kılavuzu

SDK aşağıdakileri uygulamalıdır:

• SandboxedUiAdapter: Bu, loadAd gibi SDK tarafından tanımlanan bir API'ye yanıt olarak yayıncıya döndürülür. Bu uygulamanın openSession() yöntemi, SDK'nın sunucularına reklam isteği göndermek ve bu istek için bir reklam görünümü hazırlamak için kullanılmalıdır.
• Session**: Bu, SandboxedUiAdapter.openSession aramasına yanıt olarak döndürülür. İstemci kitaplığının reklam kullanıcı arayüzünü almasını ve SDK'yı bu API'deki değişiklikler hakkında bilgilendirmesini sağlar. Tüm Session yöntemleri burada uygulanmalıdır.

Yayıncı aşağıdakileri yapmalıdır:

1. XML aracılığıyla veya programatik olarak bir SandboxedSdkView oluşturun.
2. Kullanıcı arayüzündeki değişiklikleri gözlemlemek için SandboxedSdkView'ye bir SandboxedSdkUiSessionStateChangedListener ekleyin.
3. SandboxedUiAdapter tarafından sağlanan bir SDK'yı SandboxedSdkView'a ekleyin.
4. Pencereye her zamanki gibi SandboxedSdkView ekleyin ve istemci kitaplığının, SDK ile kullanıcı arayüzü oturumunu oluşturup sürdürmesini sağlayın.
5. Uygun zamanlarda, SandboxedSdkUiSessionChangedListener tarafından bildirilen durumdaki değişikliklere tepki verin. Örneğin, SDK oturumu beklenmedik bir şekilde kapatırsa yayıncı, SandboxedSdkView öğesini statik bir resimle değiştirebilir veya görüntüleme hiyerarşisindeki yerinden kaldırabilir.
6. Açılır menü gibi reklam kullanıcı arayüzünü kapatabilecek geçişler yaparken reklam kullanıcı arayüzünü yayıncının penceresinin altına yerleştirmek için orderProviderUiAboveClientUi değerini geçici olarak false olarak ayarlayın. Açılır menü kapatıldıktan sonra orderProviderUiAboveClientUi ile true arasında arama yapın.

Platform API'lerinin geleceği

Kullanıcı arayüzü kitaplıkları Beta sürümüne geçtikten sonra, kullanıcı arayüzü sunumuyla ilgili SDK çalışma zamanı platform API'lerinin (SdkSandboxManager.requestSurfacePackage() ve SandbxedSdkProvider.getView()) desteğini sonlandırmayı planlıyoruz.

Açık uçlu sorular

1. Kullanıcı arayüzü kitaplıklarının otomatik olarak ele alması gereken daha yaygın reklam kullanıcı arayüzü kullanım alanları var mı?
2. Reklam kullanıcı arayüzünü göstermek için hangi kullanıcı arayüzü çerçevelerini kullanıyorsunuz? Kullanıcı arayüzü kitaplıklarını bu çerçevelerle entegre ederken sorun yaşayacağınızı düşünüyor musunuz?
3. Kaydırılabilir bir yayıncı kapsayıcısına yerleştirilmiş kaydırılabilir reklam kullanıcı arayüzü sizin için yaygın bir kullanım alanı mıdır? Bu durumda reklam kullanıcı arayüzü ve kapsayıcı için kaydırma yönü nedir? Kullanıcı reklam kullanıcı arayüzünde kaydırma işlemi başlattığında ne tür bir davranışı bekliyorsunuz?