Tam ekran reklamlar için etkinlik desteği

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ı, SDK'ların yeni etkinlikleri nasıl başlatabileceği konusunda kısıtlamalar uygular. Bu durum, genellikle gelişmiş kontrol ve kullanıcı deneyimi için ayrı bir etkinlik başlatmaya dayanan tam ekran reklam biçimleri için bir sorun teşkil eder. SDK Çalışma Zamanı, bu sorunu gidermek için korumalı alan etkinlikleri için yeni bir mekanizma sunar.

SDK Çalışma Zamanı ortamına yüklenen SDK'lar, manifestlerinde doğrudan <activity> etiketleri tanımlayamaz veya kendi etkinliklerini başlatamaz. Bunun yerine, START_SANDBOXED_ACTIVITY adlı yeni bir intent işlemi kullanıma sunulur.

SDK'ların bu işlemle intent başlatması da kısıtlanmış olsa da SDK'lar istemci uygulamasından bu intent'i başlatmasını isteyebilir. Sistem daha sonra platform tarafından tanımlanan bir etkinlik oluşturur ve bunu SDK'ya iletir. Bu etkinlik, SDK ile aynı işlemde çalışır.

SDK, tam ekran reklam deneyimini uygulamak ve yönetmek için bu etkinliği kullanabilir.

Platform tarafından sağlanan etkinlik, istemci uygulamasının görevi kapsamında başlatılan standart bir android.app.Activity'tır.

Dikkat: Sağlanan etkinlik (android.app.Activity), SDK tarafında bazı AndroidX kitaplıkları (özellikle Compose) için sınırlı destek sunar.

Dikkat: Bu etkinliğin Context doğrudan SDK tarafından kullanılmamalıdır. Bunun yerine SDK'lar, işlemleri için uygun bağlamı elde etmek üzere SandboxedSdkProvider#getContext() kullanmalıdır.

SDK Çalışma Zamanı'nda etkinlik oluşturma

Etkinlik oluşturmak için iki temel yönteminiz vardır: basitleştirilmiş Jetpack etkinlik kitaplıklarını kullanmak veya doğrudan Platform API'leriyle etkileşim kurmak.

Temel karmaşıklığı soyutlayarak etkinlik oluşturmayı basitleştirdikleri için etkinlik kitaplıklarını kullanmanızı öneririz.

Etkinlik kitaplıkları

Etkinlik kitaplıkları çeşitli avantajlar sağlar:

• Etkinlik işleyicileri kaydetme ve tanımlayıcılarını istemci uygulamalarıyla paylaşma işlemlerinin dahili ayrıntılarını soyutlayın.
• Uygulama geliştiricilere, SDK'ların uygulamaları içinde etkinlikleri nasıl oluşturduğu konusunda daha fazla kontrol olanağı sunar. Bu sayede geliştiriciler, karşılanması gereken koşulları (öncüller) belirleyebilir.
• SDK'ların etkinlikleri başlatan API'leri tanımlaması için birleşik bir yol oluşturun.

Üç etkinlik kitaplığı vardır: temel, istemci ve sağlayıcı.

• Core kitaplığı, istemci uygulamaları ve sağlayıcı kitaplıkları tarafından kullanılan arayüzleri sağlar.
• Sağlayıcı kitaplığı, SDK'ların etkinlikleri başlatması için API'ler sağlar.
• İstemci kitaplığı, istemci uygulamaların etkinlik başlatıcı oluşturması için API'ler sağlar. SDK'lar, uygulamaların etkinlikleri başlatmasını istemek için bu API'leri kullanabilir.

Bu kitaplıklar aşağıdaki API'leri kullanıma sunar:

• SdkActivityLauncher: Etkinlik başlatıcı, SDK'ların istemci uygulamasından etkinlik başlatmasını sağlar. İstemci uygulamaları bir başlatıcı oluşturmalı ve bunu SDK'nın etkinlikleri başlatan API'lerine parametre olarak iletmelidir.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): İstemci uygulamasının başlatıcı oluşturmak için etkinliklerinden çağırabileceği bir uzantı işlevi.
• SdkActivityLauncher.launchSdkActivity(IBinder): SDK'nın, uygulamadan etkinlik başlatmasını istemek için kullandığı bir yöntemdir.

Etkinlik kitaplıklarıyla etkinlik başlatma akışı aşağıdaki gibidir:

1. SDK, etkinlikleri başlatacak tüm API'lere SdkActivityLauncher türündeki bir parametre ekler.
2. İstemci uygulaması, API çağrılarında SDK'ya iletilebilecek bir başlatıcı oluşturmak için etkinliklerinden birinde createSdkActivityLauncher çağrısı yapar.
3. SDK, SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) işlevini çağırır ve tanımlayıcı jetonunu alır.
4. SDK, etkinliği başlatmak için launchSdkActivity çağrısını yapar.

Not: Müşteri uygulaması, SDK'ların etkinlik oluşturması için bir koşul eklemek istiyorsa başlatıcıyı oluştururken bir önerme ifadesi iletebilir. Uygulama, etkinlik oluşturmayı koşullandırmak istemiyorsa önerme her zaman true döndürebilir.

Aşağıdaki şemada, etkinlik kitaplıklarının kullanılması durumundaki akış gösterilmektedir.

Etkinlik kitaplıkları kullanılarak etkinlik başlatma akışını gösteren sıra şeması.

Platform API'leri

Platform, SDK Çalışma Zamanı'nda korumalı alan etkinliklerinin oluşturulmasını ve yönetimini kolaylaştırmak için aşağıdaki API'leri kullanıma sunar:

• SdkSandboxActivityHandler: Etkinlik işleyici, bir etkinlik oluşturulduğunda SDK'yı bilgilendirmek için kullanılır ve SDK tarafından kaydedilir.
• SDK, etkinlik işleyicilerinin kaydedilmesine yardımcı olmak için SdkSandboxController altında aşağıdaki yöntemleri kullanabilir:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): SdkSandboxActivityHandler örneği kaydeder. Bu işlem, IBinder tanımlayıcısı döndürür.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): SdkSandboxActivityHandler sınıfının kayıtlı bir örneğinin kaydını, tanımlayıcısını kullanarak siler.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): İstemci uygulamasından çağrılan bu yöntem, SDK için etkinliklerin oluşturulmasını tetikler. İstemci uygulamasının, seçtiği başlangıç etkinliğini ve SDK'nın Etkinlik İşleyicisi tanımlayıcısını parametre olarak iletmesi gerekir.

Platform API'lerini kullanarak bir etkinlik başlatmak için SDK'ların şu akışı uygulaması gerekir:

1. SDK, sağlanan API'leri kullanarak bir etkinlik işleyici kaydeder ve bir tanımlayıcı elde eder.
2. SDK bu tanımlayıcıyı istemci uygulamasıyla paylaşır.
3. İstemci uygulaması, platform API'si startSdkSandboxActivity(Activity, IBinder) ile SDK çalışma zamanında bir etkinliği başlatma yöntemini çağırır. Bu yeni etkinlik için seçilen başlangıç etkinliğini ve etkinlik işleyicinin tanımlayıcısını parametre olarak iletir.
4. Platform bir etkinlik başlatır ve Etkinlik İşleyici'deki (SdkSandboxActivityHandler.onActivityCreated(Activity)) geri çağırma işlevi aracılığıyla SDK'yı bilgilendirir.
5. SDK, etkinliği reklamla doldurmak için kullanır.

Not: onActivityCreated(Activity), Activity.onCreate(Bundle) aracılığıyla çağrılır. Bu aşamada SDK'ların içerik görünümünü doldurması beklenir.

Platform API'lerinin kullanılması, SDK'nın SdkSandboxActivityHandler tanımlayıcısını API'leri aracılığıyla istemci uygulamasıyla uygun bir zamanda paylaşmasından ve istemci uygulamalarını bu tanımlayıcının nasıl kullanılacağı konusunda yönlendirmesinden sorumlu olmasını sağlar.

Aşağıdaki akış şemasında, örnek SDK'da geri çağırma işlevi (SDK'nın API'sinin bir parçası olarak tanımlanır) bekleyen bir launchActivity(AppCallback) yöntemi vardır. Bu geri çağırma, SDK tarafından Etkinlik İşleyici'nin (SdkSandboxActivityHandler) tanımlayıcısını istemci uygulamasıyla paylaşmak için kullanılır.

Platform API'lerini kullanarak etkinlik başlatma akışını gösteren ardışık düzen şeması.

Görüntülenebilirlik

SDK Çalışma Zamanı'nda, istemci uygulamasının görüntü hiyerarşisine entegre edilen reklamlar, SDK görünümlerini SDK işleminden istemci uygulamasının işlemine oluşturmak için yan kanalları kullanır.

Reklam görünümü uygulamanın penceresine eklenmediğinden (Görünürlük) SDK, reklamın kullanıcı tarafından görülebilip görülemediğini belirlemek için SDK çalışma zamanından farklı görüntüleme API'lerini kullanamaz.

Buna karşılık, platform tarafından sağlanan etkinlik SDK Çalışma Zamanı sürecinde yerel olarak çalışır. Bu sayede yan kanallara ihtiyaç duyulmaz ve SDK'ların standart Android Activity ve View API'lerini kullanmasına izin verilir.

Bu farklı uygulamalar nedeniyle, devam eden çalışmalarda, reklam yükleme bağlamından bağımsız olarak görüntülenebilirlik sinyallerini almak için arayüzleri birleştirmek amaçlanıyor.

Yaşam döngüsü

SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) aracılığıyla SDK'ya iletilen ActivityHolder, LifecycleOwner'ı uygular ve Lifecycle.Event hakkında bilgi edinmek için kullanılabilir.

Geri gezinme

ActivityHolder.getOnBackPressedDispatcher() yöntemi, geri gezinmeyi işlemek için OnBackPressedCallback örneklerini kaydetmek üzere kullanılabilen OnBackPressedDispatcher döndürür.