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ıştırılmasına olanak tanıyarak reklam SDK'larının çalışmasını engeller. erişimi engellenebilir. Reklam göstermek için platform, reklam almak için SDK'ya bir SandboxedSdkProvider.getView API sunar görünümünü alır ve IPC üzerinden gönderilecek bir SurfacePackage olarak paketler (süreçler arası iletişim) istemcinin kendi uygulamaya Bunun birkaç dezavantajı vardır. Bunlar aşağıda açıklanmıştır. Bu doküman, projeniz için önerilen bir Bu zorlukların üstesinden gelmek için geliştirilen Jetpack kitaplığını kullanıyor.

Platform API'lerinin kapsamını genişletmenin gerekçesi

Çerçeve API'leri esneklik sağlamak için tasarlanmıştır ve bu API'ler, esnek bir kullanıcı arayüzü sunumu için uygulamaya ve SDK'ya kadar olan yan kanal. Bu taraf şunları yapar:

  1. SDK'nın kullanım ömrü boyunca birden fazla reklam görüntülemesini yönetmesine ve reklam kullanıcı arayüzü SDK tarafından oluşturulduktan sonra buna ne olduğu.
  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. Kullanıcı arayüzünü daha fazla bilgi edineceksiniz. (Platformda şu anda SurfaceControlViewhost ve buradan bir SurfacePackage oluşturur.)
  4. SDK Çalışma Zamanı'ndaki reklam SDK'larının otomatik olarak bildirim almasını sağlar Reklam kapsayıcısının kullanıcı arayüzü değiştiğinde. Bir yayıncı reklam kapsayıcı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. Reklam kullanıcı arayüzünün ve reklam kapsayıcısının yeniden boyutlandırmalarını, kullanıcının görebildiği olumsuzluklar.
  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 uygulamadan uzaklaştırır geliştirici kodumuz.
  7. Reklam kullanıcı arayüzünün Composables ile sorunsuz şekilde entegre edilmesini sağlar. Görünüm kullanmayan Jetpack Compose geliştiricileri, görünüm kullanmaya 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 cihaz arasında etkileşim gerçekleşirken kullanıcı arayüzünü 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şturulup içerik alma yöntemi sağlar Yayıncının arayüzünde görüntülenecektir.

SandboxedSdkView: Yayıncı tarafından oluşturulan bu kapsayıcı, SandboxedUiAdapter aracılığıyla edinilen içerik.

Session: SDK tarafından şuna yanıt olarak oluşturulmuştur: SandboxedUiAdapter.openSession(). 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'si ilişkilerini gösteren görsel.
SDK Runtime kullanıcı arayüzü sunum API'leri arasındaki ilişkiler.

Daha ayrıntılı bilgi için privacysandbox-ui referans dokümanlarını okuyun. bu API'lerden yararlanabilirsiniz.

Akışı kontrol etme

Aşağıdaki diyagramlarda, istemci ve sağlayıcı kullanıcı arayüzü arasındaki etkileşim gösterilmektedir kitaplıklardan faydalanabilirsiniz:

Ö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. Tüm kullanıcı arayüzü durumunu gözlemlemek için yayıncının bir SandboxedSdkUiSessionStateChangedListener ekleme yapması gerekir. SdkSandboxUiAdapter öğesini eklemeden önce SandboxedSdkView konumuna gönderin.

Açık oturum işlemini gösteren görsel.
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ının şu gibi etkileşimleri sonucunda gerçekleşebilir: mraid.resize()

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

Bu diyagramda, SandboxedSdkView pencereden ayrıldığında oturumun nasıl kapatılacağı gösterilmektedir. Oturum, SDK tarafından SessionClient.onSessionError() çağrılarak da herhangi bir noktada (ö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 sayfasının üzerinde göstermek için Z sırasını kullanabilir herhangi bir yeri seçebilirsiniz. Bu, SandboxedSdkView.orderProviderUiAboveClientUi() yöntemi kabul edilir ve boole değeri: setOnTop.

setOnTop true olduğunda, SandboxedSdkView üzerindeki her android.view.MotionEvent SDK'ya gönderilir. false olduğunda bu bildirimler yayıncısına ait. 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 açılır menü gibi bir reklamı kapsayan kullanıcı arayüzü gösterilirken Z sırası geçici olarak varsayılan düzenden ters çevrilmiş, ardından kapsayan kullanıcı arayüzü öğesi kapatılır. Bu süreci otomatikleştirmenin yollarını arıyoruz işlemi gerçekleştireceğiz.

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 kaydırma hareketleri, yayıncının anlamına gelir. 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 ek bir çalışma gerekmez.
  2. Yatay kaydırma ve 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ı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 arama. Projenin gidişatı boyunca SDK'yı bu API'de yapılan değişiklikler hakkında bilgilendirin. 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. Şuna bir SandboxedSdkUiSessionStateChangedListener ekleyin: Kullanıcı arayüzündeki değişiklikleri gözlemlemek için SandboxedSdkView.
  3. SandboxedUiAdapter ile sağlanan bir SDK'yı SandboxedSdkView öğesine ekleyin.
  4. SandboxedSdkView öğesini pencereye her zamanki gibi ekleyin ve istemci kitaplığının SDK ile kullanıcı arayüzü oturumunu oluşturma ve sürdürme
  5. Uygun zamanlarda, SandboxedSdkUiSessionChangedListener tarafından bildirilen durumdaki değişikliklere tepki verin. Örneğin, SDK oturum beklenmedik bir şekilde, yayıncı SandboxedSdkView öğesini bir veya görünüm hiyerarşisinden kaldırmalarını sağlayabilirsiniz.
  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 geçici olarak orderProviderUiAboveClientUi değerini 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 sorular

  1. Kullanıcı arayüzü kitaplıklarının kullanılması gereken daha yaygın reklam kullanıcı arayüzü kullanım alanları var mı? otomatik olarak işlensin mi?
  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? Reklam kullanıcı arayüzü ve kapsayıcı mı? Kullanıcı bir anahtar kelime öbeğini başlattıktan sonra nasıl bir davranış kaydırılırsa ne olur?