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

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:

  1. 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.
  2. 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.
  3. İş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 bir SurfacePackage üretiyor.)
  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. 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.
  5. 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.
  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 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çin SurfacePackage oluşturmak israfa yol açar. Yan kanal, bu karmaşıklığı SDK ve uygulama geliştirici kodundan soyutlar.
  7. 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.

SDK Çalışma Zamanı Kullanıcı Arayüzü sunusu API ilişkilerini gösteren görsel
SDK Çalışma Zamanı kullanıcı arayüzü sunum API'leri arasındaki ilişkiler.

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.

Açık oturum işlemini gösteren görsel.
SDK'dan kullanıcı arayüzü alma.

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.

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

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.

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

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.

Kullanıcı arayüzü oturumunu kapatma.

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:

  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, SDK veya yayıncının fazladan çalışmasını gerektirmez.
  2. 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ın openSession() 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ü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 öğesine bir SandboxedSdkUiSessionStateChangedListener ekleyin.
  3. SandboxedUiAdapter öğesi tarafından sağlanan SDK'yı SandboxedSdkView öğesine ekleyin.
  4. 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.
  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 bunu kendi görünüm hiyerarşisinden kaldırabilir.
  6. 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ı telefona orderProviderUiAboveClientUi 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

  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çevelerle entegre etme konusunda sorun öngörüyor musunuz?
  3. 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?