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

SDK Çalışma Zamanı, reklam SDK'larının korumalı alan ortamında çalışmasına olanak tanır ve yayıncının görünüm hiyerarşisine erişmesini engeller. Platform, reklamları göstermek için SDK'ya bir SandboxedSdkProvider.getView API sunarak reklam görünümü elde eder ve bunu IPC (işlemler arası iletişim) üzerinden istemci uygulamasına gönderilecek bir SurfacePackage olarak paketler. Bu durumun bazı dezavantajları vardır. Bunlar aşağıda açıklanmıştır. Bu belgede, bu zorlukları gidermek için oluşturulan önerilen bir Jetpack kitaplığı sunulacaktır.

Platform API'lerini artırmanın gerekçesi

Ç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 şunları yapar:

1. SDK'nın, kullanım ömrü boyunca birden fazla reklam görünümünü yönetmesine ve SDK tarafından oluşturulduktan sonra reklam kullanıcı arayüzünde neler olduğunu anlamasına olanak tanır.
2. Görünüm oluşturma ve içerik bağlama işlemlerini birbirinden ayırır. Yan kanalın kullanılması, SDK'nın reklam isteğine karşılık gelen bir nesneyi uygulamaya (içerik) döndürmesine olanak tanır. Bu nesne, uygulama uygun gördüğü zaman reklam kapsayıcısına bağlanabilir.
3. Süreçler arasında kullanıcı arayüzü göstermek için kullanılan temel platform yapılarını soyutlar. (Platform şu anda SurfaceControlViewhost kullanıyor ve bundan SurfacePackage oluşturuyor.)
4. SDK Çalışma Zamanı'ndaki reklam SDK'larının, reklam kapsayıcısının kullanıcı arayüzü değiştiğinde otomatik olarak bildirim almasını sağlar. Yayıncı, reklam kapsayıcısının düzenini değiştirirse yayıncı, SDK'yı bilgilendirmek için açıkça bir API çağırmadığı sürece SDK bu değişikliklerden haberdar olmaz.
5. Kullanıcı tarafından görülebilen herhangi bir titreme olmadan reklam kullanıcı arayüzü 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ıya özel süreç olduğu cihazlarda, görünüm doğrudan SDK'dan alınabildiğinde reklam için SurfacePackage oluşturmak gereksizdir. Yan kanal, bu karmaşıklığı SDK ve uygulama geliştirici kodundan uzaklaştırır.
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ü de barındırmaya 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ı ile SDK'nın süreçler arasında kullanıcı arayüzü göstermek, kullanıcı etkileşimde bulundukça ve cihazla etkileşimde bulundukça 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ı (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, bir kullanıcı arayüzü oturumu oluşturmak ve sürdürmek için gereken yan kanalı oluşturur.

API'ler

SDK Çalışma Zamanı kullanıcı arayüzü sunumu için kullanılan 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 sunar.

SandboxedSdkView: Yayıncı tarafından oluşturulan bu öğe, SandboxedUiAdapter aracılığıyla elde edilen içerikleri barındıran bir kapsayıcıdır.

Session: SDK tarafından SandboxedUiAdapter.openSession() yanıtı olarak 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'daki değişikliklerle ilgili bildirimleri (ör. pencere ayırma, yeniden boyutlandırma veya yapılandırma değişiklikleri) alır.

SessionClient: İstemci kitaplığı tarafından oluşturulur. SDK ile yayıncı arasındaki iletişim tünelinin yayıncı ucunu oluşturur.

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

Bu API'ler hakkında daha fazla bilgi edinmek için privacysandbox-ui referans belgelerini inceleyin.

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 nasıl programatik olarak veya XML'si aracılığıyla bir SandboxedSdkView oluşturabileceği ve bunu SDK tanımlı bir API aracılığıyla SDK'dan alınan bir SdkSandboxUiAdapter'ye nasıl ekleyebileceği gösterilmektedir. Tüm kullanıcı arayüzü durumu değişikliklerini gözlemlemek için yayıncı, SandboxedSdkUiSessionStateChangedListener SandboxedSdkView öncesinde SdkSandboxUiAdapter eklemelidir.

Bu şemada, yayıncının etkinliği yapılandırma değişikliklerini işlediğinde istemci kitaplığının yapılandırma değişikliğini SDK'ya nasıl ilettiği gösterilmektedir. Böylece, yayıncılar kullanıcı arayüzlerini buna göre güncelleyebilir. Örneğin, kullanıcı cihazı döndürdüğünde ve yayıncı, android:configChanges=["orientation"] ayarını yaparak etkinliklerinde yapılandırma değişikliklerini işlediğini bildirdiğinde bu akış tetiklenebilir.

Bu şemada, SDK'nın SessionClient üzerindeki yöntemleri kullanarak reklam kapsayıcısında nasıl değişiklik isteyebileceği gösterilmektedir. Bu API, SDK reklamı yeniden boyutlandırmak istediğinde ve yayıncının yeni boyutlara uyum sağlamak için reklam kapsayıcısını yeniden boyutlandırması gerektiğinde tetiklenir. Bu durum, kullanıcı etkileşimine yanıt olarak gerçekleşebilir. Örneğin, mraid.resize().

Bu şema, SandboxedSdkView pencereden ayrıldığında oturumun nasıl kapatıldığını gösterir. Oturum, herhangi bir noktada (ör. kullanıcı ağ bağlantısını kaybettiğinde) SDK tarafından SessionClient.onSessionError() çağrılarak da kapatılabilir.

Z sırası

İstemci kullanıcı arayüzü kitaplığı, SDK'nın kullanıcı arayüzünü barındırmak için dahili olarak 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, bir boolean setOnTop kabul eden SandboxedSdkView.orderProviderUiAboveClientUi() yöntemiyle kontrol edilir.

setOnTop true olduğunda SandboxedSdkView üzerindeki her android.view.MotionEvent, SDK'ya gönderilir. false olduğunda bunlar yayıncıya gönderilir. Varsayılan olarak, hareket etkinlikleri SDK'ya gönderilir.

Yayıncıların genellikle reklam görünümlerinin varsayılan Z sırasını değiştirmesi gerekmez. Ancak bir reklamı kaplayan kullanıcı arayüzü (ör. açılır menü) gösterilirken Z sırası geçici olarak varsayılandan farklı bir sıraya alınmalı ve kaplayan kullanıcı arayüzü öğesi kapatıldığında geri yüklenmelidir. Bu süreci istemci kullanıcı arayüzü kitaplığında otomatikleştirmenin yollarını araştırıyoruz.

Kaydırıyor

Reklam kullanıcı arayüzü, yayıncı penceresinin Z-üstünde sıralandığında reklam kullanıcı arayüzünden MotionEvents SDK'ya gönderilir. Reklam kullanıcı arayüzünde başlatılan kaydırma ve hızlıca kaydırma hareketleri özel işlem görür:

1. Dikey kaydırma ve hızlıca kaydırma 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ı kapsayıcısı 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 yapılması gerekmez.
2. Yatay kaydırma ve hızlıca kaydırma hareketleri SDK'ya gönderilir ve SDK tarafından işlenir. Bu, reklam kullanıcı arayüzü yatay olarak kaydırılabildiğinde (ör. reklam bandı) iyi bir kullanıcı deneyimi sağlar.

Uygulama kılavuzu

SDK'da aşağıdakiler uygulanmalıdır:

• SandboxedUiAdapter: Bu, loadAd gibi SDK tanımlı 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ğinde bulunmak ve bu istek için bir reklam görünümü hazırlamak üzere kullanılmalıdır.
• Session**: Bu, SandboxedUiAdapter.openSession çağrısına yanıt olarak döndürülür. Bu, istemci kitaplığının reklam kullanıcı arayüzünü alması ve SDK'yı bu API'deki değişiklikler hakkında bilgilendirmesi için bir yol sağlar. Tüm Session yöntemleri burada uygulanmalıdır.

Yayıncı şunları yapmalıdır:

1. XML veya programatik olarak SandboxedSdkView oluşturun.
2. Kullanıcı arayüzündeki değişiklikleri gözlemlemek için SandboxedSdkUiSessionStateChangedListener dosyasını SandboxedSdkView'ye ekleyin.
3. SandboxedUiAdapter tarafından sağlanan bir SDK'yı SandboxedSdkView'ye ekleyin.
4. Pencereye her zamanki gibi SandboxedSdkView ekleyin. İstemci kitaplığı, SDK ile kullanıcı arayüzü oturumunu oluşturup sürdürmeyi halleder.
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 yerine statik bir resim yerleştirebilir veya bunu görünüm hiyerarşisinden kaldırabilir.
6. Reklam kullanıcı arayüzünü kaplayabilecek geçişler (ör. açılır menü) yaparken reklam kullanıcı arayüzünü yayıncının penceresinin altına yerleştirmek için geçici olarak orderProviderUiAboveClientUi değerini false olarak ayarlayın. Açılır menü kapatıldıktan sonra orderProviderUiAboveClientUi işlevini true ile çağırı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ı platformu API'lerinin (SdkSandboxManager.requestSurfacePackage() ve SandbxedSdkProvider.getView()) desteğini sonlandırmayı planlıyoruz.

Açık sorular

1. Kullanıcı arayüzü kitaplıklarının otomatik olarak işlemesi 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çevelere entegre ederken sorun yaşayacağınızı düşünüyor musunuz?
3. Kaydırılabilir reklam kullanıcı arayüzünün kaydırılabilir yayıncı kapsayıcısına yerleştirilmesi sizin için yaygın bir kullanım alanı mı? 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 nasıl bir davranış bekliyorsunuz?