SDK Çalışma Zamanı, reklam SDK'larının korumalı alana alınmış bir ortamda çalışmasına olanak sağlayarak, yayıncının görünüm hiyerarşisine erişmelerini engeller. Platform, reklam görüntülemek için SDK'ya bir SandboxedSdkProvider.getView
API'si sunarak reklam görüntülemesi elde eder ve bunu, IPC (işlem arası iletişim) üzerinden istemci uygulamasına gönderilecek bir SurfacePackage
olarak paketler. Bu durumun, aşağıda açıklanan bazı dezavantajları vardır. Ardından bu dokümanda, bu zorlukları ele almak üzere oluşturulmakta olan önerilen bir Jetpack kitaplığı sunulur.
Platform API'lerini genişletme gerekçesi
Çerçeve API'leri esneklik sağlayacak şekilde tasarlanmıştır. Bu API'ler, uygulama ile SDK arasındaki arayüz sunumu için, uygulama ile SDK arasında bir yan kanal oluşturma görevini bırakır. Bu yan kanal, şunları yapar:
- SDK'nın, kullanım ömrü boyunca birden fazla reklam görüntülemeyi yönetmesini ve SDK tarafından oluşturulduktan sonra reklam kullanıcı arayüzüne ne olduğunu anlamasını sağlar.
- Görünüm oluşturma ve içerik bağlamayı ayırır. Yan kanalın kullanılması SDK'nın uygulamaya (içerik) reklam isteğine karşılık gelen bir nesne döndürmesine olanak tanır. Bu nesne, uygulama uygun bulduğunda reklam kapsayıcısına bağlanabilir.
- İşlemler arasında 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 birSurfacePackage
üretiyor.) - 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. Bir yayıncı reklam kapsayıcısının düzenini değiştirirse yayıncı açıkça bir API'yi bilgilendirmek için çağrıda bulunmadığı sürece SDK bu değişikliklerden habersiz kalır.
- Reklam kullanıcı arayüzünün ve reklam kapsayıcının yeniden boyutlandırmalarını, kullanıcılar tarafından görülebilen herhangi bir olumsuzluk olmadan senkronize eder.
- 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 bulunmadığı ve SDK'nın yayıncı için yerel bir işlem olduğu cihazlarda, doğrudan SDK'dan bir görüntüleme elde edilebildiğinde bir reklam içinSurfacePackage
oluşturmak israfa yol açar. Yan kanal, bu karmaşıklığı SDK ve uygulama geliştirici kodundan soyutlar. - Reklam kullanıcı arayüzünün Composable ile sorunsuz bir şekilde entegre olmasını sağlar. Görünümlerle çalışmayan Jetpack Compose geliştiricileri de görünümlerle çalışmaya devam eden SDK geliştiricisinin oluşturduğu kullanıcı arayüzünü barındırmaya devam edebilir.
Kullanıcı arayüzü kitaplıkları
Kullanıcı arayüzü kitaplıkları, yukarıda ayrıntılı bir şekilde açıklanan karmaşıklıkları soyutlar ve yayıncı ile SDK'nın işlemler genelinde kullanıcı arayüzünü göstermek için kullanabileceği yan kanalı sağlar ve kullanıcı hem arayüzle hem de cihazla etkileşim kurdukça bu kanalı güncel tutar.
Üç kullanıcı arayüzü kitaplığı vardır: core, client ve provider. Çekirdek 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 Çalışma Zamanı Kullanıcı Arayüzü sunumu için API'lar aşağıdaki gibidir:
SandboxedUiAdapter
: SDK tarafından oluşturulur, yayıncının kullanıcı arayüzünde görüntülenecek 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()
'a yanıt olarak SDK tarafından oluşturulur. Bir UI session. çağrısını temsil eder. Bu işlem, SDK ile yayıncı arasındaki iletişim tünelinin SDK sonunu oluşturur ve pencere ayırma, yeniden boyutlandırma veya yapılandırma değişiklikleri gibi SandboxedSdkView
değişiklikleri hakkında bildirimler alır.
SessionClient
: İstemci kitaplığı tarafından oluşturulan bu API, SDK ile yayıncı arasındaki iletişim tünelinin yayıncı ucunu oluşturur.
SandboxedSdkUiSessionStateChangedListener
: Yayıncı tarafından oluşturulmuştur. SandboxedSdkView
ile ilişkili kullanıcı arayüzü oturumunun durumundaki değişiklikleri işleyici.
Bu API'ler hakkında daha ayrıntılı bilgi için privacysandbox-ui referans belgelerini okuyun.
Kontrol akışı
Aşağıdaki şemalarda, çeşitli senaryolarda istemci ve sağlayıcı kullanıcı arayüzü kitaplıkları arasındaki etkileşim gösterilmektedir:
Önceki şemada, yayıncının programatik veya XML dosyası aracılığıyla bir SandboxedSdkView
oluşturup bunu SDK'dan alınan bir API aracılığıyla SDK'dan alınan SdkSandboxUiAdapter
öğesine 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
eklemeden önce SandboxedSdkView
öğesine bir SandboxedSdkUiSessionStateChangedListener
eklemesi gerekir.
Bu şema, yayıncının etkinliğinin yapılandırma değişikliklerini ele alması durumunda istemci kitaplığının, yapılandırma değişikliğini SDK'ya iletme işlemini nasıl yaptığını gösterir. Böylece yayıncı, kullanıcı arayüzünü uygun şekilde güncelleyebilir. Örneğin, kullanıcı cihazı döndürdüğünde ve yayıncı, android:configChanges=["orientation"]
ayarını yaparak etkinliklerindeki yapılandırma değişikliklerinin ele alındığını bildirdiğinde bu akış tetiklenebilir.
Bu şema, SDK'nın SessionClient
adresindeki yöntemleri kullanarak reklam kapsayıcısında nasıl değişiklik isteyebileceğini gösterir. SDK, reklamı yeniden boyutlandırmak istediğinde ve yayıncının reklam kapsayıcısını yeni boyutları kapsayacak şekilde yeniden boyutlandırmasını istediğinde bu API tetiklenir. Bu durum, mraid.resize()
gibi kullanıcı etkileşimlerine bağlı olarak gerçekleşebilir.
Bu şema, SandboxedSdkView
pencereden ayrıldığında oturumun nasıl kapatıldığını gösterir. Ayrıca oturum, SDK tarafından herhangi bir noktada (ör. kullanıcı ağ bağlantısını kaybettiğinde) SessionClient.onSessionError()
yöntemini çağırarak 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ı penceresinin üstünde veya altında göstermek için Z sırasını kullanabilir. Bu, boole setOnTop
kabul eden SandboxedSdkView.orderProviderUiAboveClientUi()
yöntemiyle kontrol edilir.
setOnTop
, true
olduğunda SandboxedSdkView
üzerindeki her android.view.MotionEvent
SDK'ya gönderilir. Bunlar false
olduğunda 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ştirmeleri gerekmez. Bununla birlikte, açılır menü gibi bir reklamı kapsayan kullanıcı arayüzü gösterilirken, Z düzeninin geçici olarak varsayılandan farklı hale döndürülmesi ve daha sonra, kapsayıcı kullanıcı arayüzü öğesi kapatıldığında geri yüklenmesi gerekir. İ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 üzerinde Z'ye sıralandığında, reklam kullanıcı arayüzündeki MotionEvents
SDK'ya gönderilir. Reklam kullanıcı arayüzünde başlatılan kaydırma ve sallama hareketleri özel olarak işlenir:
- 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, SDK veya yayıncının fazladan çalışmasını gerektirmez.
- Yatay kaydırma ve hızlı kaydırma hareketleri SDK'ya gönderilir ve SDK tarafından işlenir. Bu, reklam kullanıcı arayüzünün yatay olarak kaydırılabildiği durumlarda (ör. reklam bandı) iyi bir kullanıcı deneyimi sağlar.
Uygulama kılavuzu
SDK, aşağıdakileri uygulamalıdır:
SandboxedUiAdapter
: Bu değer,loadAd
gibi SDK tanımlı bir API'ye yanıt olarak yayıncıya döndürülür. SDK'nın sunucularına bir reklam isteği göndermek ve bu istek için bir reklam görünümü hazırlamak üzere bu uygulamanınopenSession()
yöntemi kullanılmalıdır.Session**
: Bu,SandboxedUiAdapter.openSession
çağrısına yanıt olarak döndürülür. İstemci kitaplığına, reklam kullanıcı arayüzünü edinip bu API'de yapılan değişiklikleri SDK'ya bildirmenin bir yolunu sunar. TümSession
yöntemleri burada uygulanmalıdır.
Yayıncı aşağıdakileri yapmalıdır:
- XML aracılığıyla veya programatik olarak bir
SandboxedSdkView
oluşturun. - Kullanıcı arayüzündeki değişiklikleri gözlemlemek için
SandboxedSdkView
öğesine birSandboxedSdkUiSessionStateChangedListener
ekleyin. SandboxedUiAdapter
öğesi tarafından sağlanan SDK'yıSandboxedSdkView
öğesine ekleyin.SandboxedSdkView
öğesini her zamanki gibi pencereye ekleyin ve SDK ile kullanıcı arayüzü oturumunu oluşturma ve sürdürme işini istemci kitaplığının yapmasına izin verin.- 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 bunu kendi görünüm hiyerarşisinden kaldırabilir. - Reklam kullanıcı arayüzünü kaplayabilecek geçişler yaptığınızda (ör. açılır menü), reklam kullanıcı arayüzünü yayıncı penceresinin altına yerleştirmek için geçici olarak
orderProviderUiAboveClientUi
. Açılır menü kapatıldıktan sonra,true
numaralı telefonaorderProviderUiAboveClientUi
numaralı telefonu arayı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'lerini (SdkSandboxManager.requestSurfacePackage()
ve SandbxedSdkProvider.getView()
) kullanımdan kaldırmayı planlıyoruz.
Açık sorular
- 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ı?
- 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 etme konusunda sorun öngörüyor musunuz?
- Kaydırılabilir reklam kullanıcı arayüzü, kaydırılabilir yayıncı kapsayıcısına yerleştirilmiş 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 arayüzünde kaydırma başlattığında nasıl bir davranış bekliyorsunuz?