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

Lưu ý: Hộp cát về quyền riêng tư trên Android là một dự án đang trong quá trình thực hiện và tài liệu này phản ánh thiết kế hiện tại của dự án. Ý kiến phản hồi của bạn rất quan trọng trong quá trình chúng tôi tiếp tục phát triển và nâng cao các tính năng của dịch vụ này.

Gửi ý kiến phản hồi

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 khởi tạo ý đị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 quy trình tương tự như SDK.

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

Hoạt động do nền tảng cung cấp là một android.app.Activity tiêu chuẩn, khởi chạy trong 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: Context của hoạt động này không nên được sử dụng trực tiếp bởi SDK. Thay vào đó, SDK phải sử dụng SandboxedSdkProvider#getContext() để lấy bối cảnh phù hợp cho hoạt động của họ.

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

Hoạt động thư viện sẽ cung cấp 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ó thêm quyền kiểm soát đối với cách SDK tạo Hoạt động trong ứng dụng 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 sử dụng và thư viện nhà cung cấp.
• 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 khách. Ứ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 các 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 của chú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 thêm một thông 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 nó để 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 gọi SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) và truy xuất mã thông báo giá trị nhận dạng.
4. SDK gọi launchSdkActivity để khởi chạy hoạt động đó.

Lưu ý: Nếu ứng dụng khách muốn thêm điều kiện để SDK tạo hoạt động, thì ứng dụng có thể chuyển 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 cách sử dụng hoạt động thư viện.

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 môi trường 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! Mã này sẽ trả về một 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.
• 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 qua Activity.onCreate(Bundle), Theo dự kiến, SDK sẽ điền sẵn 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ẻ của SdkSandboxActivityHandler giá trị nhận dạng với ứng dụng khách thông qua API của ứng dụng đó tại thời điểm thích hợp, và hướng dẫn ứng dụng về cách sử dụng API này.

Trong sơ đồ quy trình sau đây, SDK mẫu có một phương thức launchActivity(AppCallback) với kỳ vọng lệnh gọi lại (được định nghĩa là một phần của API của SDK). Lệnh gọi lại này được sử dụng bởi SDK để chia sẻ của Trình xử lý hoạt động (SdkSandboxActivityHandler) giá trị nhận dạng 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ẽ sử dụng bên các kênh để hiển thị khung hiển thị SDK từ quy trình SDK sang quy trình của ứng dụng.

SDK không thể dùng cùng một 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ì lượt xem quảng cáo không được đính kèm vào 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, những nỗ lực không ngừng nhằm hợp nhất để 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

Chiến lược phát hành đĩa đơn ActivityHolder được chuyển đến SDK thông qua SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) implements LifecycleOwner và có thể dùng để biết về Lifecycle.Event.

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

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