Hỗ trợ hoạt động cho quảng cáo toàn màn hình

Thời gian chạy SDK áp đặt các hạn chế về cách SDK có thể khởi chạy các hoạt động mới. Điều này đặt ra một thách thức đối với những định dạng quảng cáo toàn màn hình thường dựa vào việc bắt đầu một hoạt động riêng biệt để tăng cường khả năng kiểm soát và trải nghiệm người dùng. Để giải quyết vấn đề này, Thời gian chạy SDK đưa ra một cơ chế mới cho các hoạt động trong môi trường hộp cát.

Các SDK tải trong môi trường Thời gian chạy SDK không thể trực tiếp xác định các thẻ <activity> trong tệp kê khai hoặc bắt đầu hoạt động của riêng chúng. Thay vào đó, một thao tác theo ý định mới là START_SANDBOXED_ACTIVITY sẽ được giới thiệu.

Mặc dù SDK cũng bị hạn chế khởi chạy ý định bằng thao tác này, nhưng SDK có thể yêu cầu ứng dụng khách bắt đầu ý định này. Sau đó, hệ thống sẽ tạo một hoạt động do nền tảng xác định rồi chuyển hoạt động đó sang SDK. Hoạt động này sẽ chạy trong cùng một quy trình với SDK.

Sau đó, SDK có thể sử dụng hoạt động này để triển khai và quản lý trải nghiệm quảng cáo toàn màn hình.

Hoạt động do nền tảng cung cấp là một android.app.Activity tiêu chuẩn, được chạy trong phạm vi tác vụ của ứng dụng khách.

Thận trọng: Hoạt động được cung cấp (android.app.Activity) chỉ hỗ trợ hạn chế một số thư viện AndroidX ở phía SDK, đặc biệt là Compose.

Thận trọng: SDK không nên sử dụng trực tiếp Context của hoạt động này. Thay vào đó, SDK phải sử dụng SandboxedSdkProvider#getContext() để có được ngữ cảnh thích hợp cho các hoạt động của chúng.

Tạo hoạt động trên Thời gian chạy SDK

Bạn có 2 phương thức chính để tạo hoạt động: sử dụng Thư viện hoạt động Jetpack được tinh giản hoặc tương tác trực tiếp với API nền tảng.

Bạn nên sử dụng thư viện Hoạt động vì thư viện này giúp đơn giản hoá việc tạo hoạt động bằng cách trừu tượng hoá những phần phức tạp cơ bản.

Thư viện hoạt động

Thư viện hoạt động có một số ưu điểm:

• Tóm tắt thông tin nội bộ về việc đăng ký trình xử lý hoạt động và chia sẻ giá trị nhận dạng của các trình xử lý này với các ứng dụng khách.
• Giúp nhà phát triển ứng dụng có nhiều quyền kiểm soát hơn đối với cách SDK tạo Hoạt động trong ứng dụng của họ bằng cách cho phép họ đặt ra các điều kiện (thuộc tính) cần được đáp ứng.
• Tạo một cách thức hợp nhất cho các SDK để xác định những API khởi chạy hoạt động.

Có 3 thư viện hoạt động: lõi, ứng dụng và nhà cung cấp.

• Thư viện core (lõi) cung cấp các giao diện mà ứng dụng khách và thư viện của nhà cung cấp sử dụng.
• Thư viện provider cung cấp các API để SDK khởi chạy các hoạt động.
• Thư viện ứng dụng cung cấp API cho ứng dụng khách để tạo trình chạy hoạt động mà SDK có thể dùng để yêu cầu ứng dụng khởi chạy các hoạt động.

Các thư viện này giới thiệu các API sau:

• SdkActivityLauncher: Trình chạy hoạt động cho phép SDK xử lý các hoạt động khởi chạy từ ứng dụng. Ứng dụng khách phải tạo một trình chạy và truyền trình chạy đó dưới dạng tham số đến API của SDK để bắt đầu hoạt động.
• <T : Activity & LifecycleOwner> T.createSdkActivityLauncher(() -> Boolean ): Một hàm tiện ích mà ứng dụng khách có thể gọi từ các hoạt động để tạo trình chạy.
• SdkActivityLauncher.launchSdkActivity(IBinder): Phương thức được SDK sử dụng để yêu cầu ứng dụng khởi chạy các hoạt động.

Quy trình khởi chạy các hoạt động bằng thư viện hoạt động như sau:

1. SDK sẽ thêm một tham số thuộc loại SdkActivityLauncher vào bất kỳ API nào sẽ bắt đầu hoạt động.
2. Ứng dụng khách gọi createSdkActivityLauncher trên một trong các hoạt động của ứng dụng đó để tạo một trình chạy có thể được chuyển đến SDK trong các lệnh gọi API.
3. SDK sẽ gọi SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) và truy xuất mã thông báo của giá trị nhận dạng.
4. SDK gọi launchSdkActivity để khởi chạy hoạt động đó.

Lưu ý: Nếu muốn thêm một điều kiện để SDK tạo hoạt động, ứng dụng khách có thể chuyển một biểu thức thuộc tính khi tạo trình chạy. Nếu không muốn điều chỉnh việc tạo hoạt động, thì ứng dụng có thể khiến thuộc tính trả về luôn true.

Sơ đồ dưới đây cho thấy quy trình trong trường hợp sử dụng thư viện hoạt động.

Sơ đồ trình tự cho thấy quy trình bắt đầu một hoạt động bằng thư viện hoạt động.

API nền tảng

Nền tảng này ra mắt các API sau đây để hỗ trợ việc tạo và quản lý các hoạt động trong hộp cát trong Thời gian chạy SDK:

• SdkSandboxActivityHandler: Trình xử lý hoạt động dùng để thông báo cho SDK khi một Hoạt động được tạo và được SDK đăng ký.
• Để hỗ trợ đăng ký Trình xử lý hoạt động, SDK có thể sử dụng các phương thức sau trong SdkSandboxController:
  • .registerSdkSandboxActivityHandler(SdkSandboxActivityHandler): Đăng ký một thực thể của SdkSandboxActivityHandler. Thực thể này trả về giá trị nhận dạng IBinder.
  • .unregisterSdkSandboxActivityHandler(SdkSandboxActivityHandler): Huỷ đăng ký một thực thể đã đăng ký của SdkSandboxActivityHandler bằng cách sử dụng giá trị nhận dạng của thực thể đó.
• SdkSandboxManager.startSdkSandboxActivity(Activity, IBinder): Được gọi từ ứng dụng khách, phương thức này sẽ kích hoạt việc tạo hoạt động cho SDK. Ứng dụng khách phải truyền dưới dạng các tham số mà Hoạt động bắt đầu đã chọn và giá trị nhận dạng Trình xử lý hoạt động của SDK.

Để bắt đầu một hoạt động bằng API nền tảng, SDK phải tuân theo quy trình sau:

1. SDK đăng ký trình xử lý hoạt động bằng cách sử dụng các API được cung cấp và lấy một giá trị nhận dạng.
2. SDK chia sẻ giá trị nhận dạng này với ứng dụng khách.
3. Ứng dụng khách gọi phương thức để bắt đầu một hoạt động trong Thời gian chạy SDK bằng API nền tảng startSdkSandboxActivity(Activity, IBinder), truyền dưới dạng các tham số bắt đầu Hoạt động đã chọn cho Hoạt động mới này và giá trị nhận dạng của Trình xử lý hoạt động.
4. Nền tảng này bắt đầu một Hoạt động và thông báo cho SDK thông qua lệnh gọi lại trong Trình xử lý hoạt động (SdkSandboxActivityHandler.onActivityCreated(Activity)).
5. SDK sử dụng hoạt động để đưa quảng cáo vào đó.

Lưu ý: onActivityCreated(Activity) được gọi thông qua Activity.onCreate(Bundle), SDK dự kiến sẽ điền vào khung hiển thị nội dung ở giai đoạn này.

Việc sử dụng API nền tảng khiến SDK có trách nhiệm chia sẻ giá trị nhận dạng của SdkSandboxActivityHandler với ứng dụng khách thông qua API vào một thời điểm thích hợp, đồng thời hướng dẫn ứng dụng khách về cách sử dụng giá trị đó.

Trong sơ đồ quy trình sau đây, SDK mẫu có một phương thức launchActivity(AppCallback) dự kiến sẽ thực hiện lệnh gọi lại (được xác định là một phần của API của SDK). Lệnh gọi lại này được SDK sử dụng để chia sẻ giá trị nhận dạng của Trình xử lý hoạt động (SdkSandboxActivityHandler) với ứng dụng khách.

Sơ đồ trình tự cho thấy quy trình bắt đầu một hoạt động bằng API nền tảng.

Khả năng xem

Trong Thời gian chạy SDK, các quảng cáo được tích hợp vào hệ phân cấp khung hiển thị của ứng dụng khách sử dụng các kênh phụ để kết xuất khung hiển thị SDK từ quy trình SDK sang quy trình của ứng dụng khách.

SDK không thể sử dụng cùng các View API (API Khung hiển thị) như chúng sử dụng bên ngoài Thời gian chạy SDK để xác định xem quảng cáo có hiển thị cho người dùng hay không, vì khung hiển thị quảng cáo không được gắn với cửa sổ của ứng dụng (Khả năng xem).

Ngược lại, hoạt động do nền tảng cung cấp sẽ chạy nguyên gốc trong quy trình Thời gian chạy SDK, giúp loại bỏ nhu cầu sử dụng các kênh phụ và cho phép SDK sử dụng các API Activity và View tiêu chuẩn của Android.

Do những cách triển khai khác nhau này, chúng tôi luôn nỗ lực nhằm hợp nhất các giao diện để truy xuất tín hiệu về khả năng xem bất kể bối cảnh tải quảng cáo.

Vòng đời

ActivityHolder được chuyển đến SDK thông qua SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) sẽ triển khai LifecycleOwner và có thể được dùng để nhận biết về Lifecycle.Event.

Tính năng điều hướng quay lại

Phương thức ActivityHolder.getOnBackPressedDispatcher() trả về OnBackPressedDispatcher có thể dùng để đăng ký các thực thể OnBackPressedCallback nhằm xử lý thao tác điều hướng quay lại.