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 diễn ra 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 YouTube Kids.

Thời gian chạy SDK áp đặt các quy định hạn chế về cách SDK có thể chạy các hoạt động mới. Điều này gây ra thách thức cho các đị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 giới thiệu một cơ chế mới cho các hoạt động trong hộp cát.

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

Mặc dù SDK cũng bị hạn chế khởi chạy ý định bằng hành động 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 và truyền hoạt động đó đến 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 khởi chạy như một phần của tác vụ của ứng dụng khách.

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

Thận trọng: SDK không được 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() để lấy 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ó hai phương pháp 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 đơn giản hoá việc tạo hoạt động bằng cách trừu tượng hoá độ phức tạp cơ bản.

Thư viện hoạt động

Thư viện hoạt động mang lại một số lợi thế:

• Tóm tắt thông tin chi tiết 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 trình xử lý đó với ứ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 các điều kiện (điều kiện tiên đề) cần đáp ứng.
• Tạo một cách thống nhất để các SDK xác định các 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 nhà cung cấp sử dụng.
• Thư viện provider (nhà cung cấp) cung cấp API cho SDK để chạy các hoạt động.
• Thư viện ứng dụng cung cấp các API cho ứng dụng khách để tạo trình chạy hoạt động. Các SDK có thể sử dụng trình chạy hoạt động này để yêu cầu ứng dụng 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 mở rộng mà ứng dụng khách có thể gọi từ các hoạt động của ứng dụng để tạo trình chạy.
• SdkActivityLauncher.launchSdkActivity(IBinder): Một phương thức mà 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 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 mọi API 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 trình chạy có thể được truyền đến SDK trên các lệnh gọi API.
3. SDK gọi SdkSandboxControllerCompat.registerSdkSandboxActivityHandler(SdkSandboxActivityHandlerCompat) và truy xuất mã thông báo 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 một điều kiện để SDK tạo hoạt động, thì ứng dụng đó có thể truyề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 kiện hoá việc tạo hoạt động, ứng dụng có thể khiến thuộc tính luôn trả về true.

Sơ đồ sau đâ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 thư viện hoạt động.

API nền tảng

Nền tảng này giới thiệu các API sau đây để tạo điều kiện cho 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ợ việc đă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 sẽ 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 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 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 tham số 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 cách sử dụ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á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 tham số Hoạt động bắt đầu đã 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 sẽ 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 này để điền 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 sẵn thành phần hiển thị nội dung ở giai đoạn này.

Việc sử dụng API Nền tảng khiến SDK chịu 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 các API của SDK tại thời điểm thích hợp và hướng dẫn ứng dụng khách cách sử dụng giá trị nhận dạng đó.

Trong sơ đồ quy trình sau, SDK mẫu có một phương thức launchActivity(AppCallback) dự kiến sẽ có một 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 cách sử dụng API nền tảng.

Khả năng xem

Trong Thời gian chạy SDK, 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 kênh phụ để hiển thị khung hiển thị SDK từ quy trình SDK đến quy trình của ứng dụng khách.

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ì khung hiển thị quảng cáo không được đính kèm vào cửa sổ của ứng dụng (Khả năng hiển thị).

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

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

Vòng đời

ActivityHolder được truyền đến SDK thông qua SdkSandboxActivityHandlerCompat.onActivityCreated(ActivityHolder) triển khai LifecycleOwner và có thể được dùng để 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. Bạn có thể dùng phương thức này để đăng ký các thực thể OnBackPressedCallback nhằm xử lý thao tác quay lại.