API trình bày giao diện người dùng trong Thời gian chạy SDK

Thời gian chạy SDK cho phép SDK quảng cáo chạy trong một môi trường hộp cát, ngăn các SDK này truy cập vào hệ phân cấp khung hiển thị của nhà xuất bản. Để hiển thị quảng cáo, nền tảng hiển thị một API SandboxedSdkProvider.getView cho SDK để lấy một khung hiển thị quảng cáo và đóng gói dưới dạng SurfacePackage rồi gửi qua IPC (cơ chế giao tiếp liên quy trình) đến ứng dụng. Điều này có một số hạn chế mà chúng ta sẽ thảo luận dưới đây. Sau đó, tài liệu này sẽ trình bày về một thư viện Jetpack đã đề xuất đang được xây dựng để giải quyết những thách thức này.

Lý do tăng cường các API nền tảng

Các API khung có thiết kế giúp mang lại tính linh hoạt và để lại nhiệm vụ tạo một kênh phụ dùng cho việc trình bày giao diện người dùng cho ứng dụng và SDK. Kênh phụ này có những chức năng sau:

1. Cho phép SDK quản lý nhiều khung hiển thị quảng cáo trong suốt thời gian hoạt động và hiểu được điều gì sẽ xảy ra với giao diện người dùng quảng cáo sau khi giao diện người dùng này được SDK tạo.
2. Tách biệt quá trình tạo khung hiển thị và liên kết nội dung. Việc sử dụng kênh phụ cho phép SDK trả về cho ứng dụng một đối tượng tương ứng với yêu cầu quảng cáo (nội dung). Đối tượng này có thể được liên kết với vùng chứa quảng cáo bất cứ khi nào ứng dụng cho là phù hợp.
3. Loại bỏ các cấu trúc nền tảng cơ bản dùng để hiện giao diện người dùng trong các quy trình. (Nền tảng này hiện sử dụng một SurfaceControlViewhost và tạo một SurfacePackage từ đó.)
4. Cho phép SDK quảng cáo trong Thời gian chạy SDK tự động nhận thông báo khi giao diện người dùng của vùng chứa quảng cáo thay đổi. Nếu nhà xuất bản thay đổi bố cục của vùng chứa quảng cáo, thì SDK sẽ không biết về những thay đổi này trừ phi nhà xuất bản gọi rõ ràng một API để thông báo điều đó.
5. Đồng bộ hoá việc đổi kích thước giao diện người dùng quảng cáo và vùng chứa quảng cáo mà không gây ra bất kỳ hiện tượng giật nào người dùng nhìn thấy được.
6. Tự động quản lý khả năng tương thích ngược. Không dùng được SurfacePackage trước API cấp 30. Ngoài ra, trên các thiết bị không có Thời gian chạy SDK và SDK là quy trình cục bộ của nhà xuất bản, việc tạo SurfacePackage cho một quảng cáo khi có thể lấy khung hiển thị trực tiếp từ SDK là điều không cần thiết. Kênh phụ giúp loại bỏ sự phức tạp này khỏi SDK và mã của nhà phát triển ứng dụng.
7. Cho phép giao diện người dùng quảng cáo tích hợp liền mạch với các Thành phần kết hợp. Các nhà phát triển dùng Jetpack Compose (không làm việc với các khung hiển thị) cũng có thể tiếp tục lưu trữ giao diện người dùng do nhà phát triển SDK (vẫn làm việc với các khung hiển thị) tạo ra.

Thư viện giao diện người dùng

Thư viện giao diện người dùng loại bỏ những vấn đề phức tạp được nêu chi tiết ở trên và cung cấp kênh phụ mà nhà xuất bản và SDK có thể sử dụng để hiện giao diện người dùng trong các quy trình, đồng thời luôn cập nhật giao diện người dùng khi người dùng tương tác với giao diện này và với thiết bị.

Có 3 thư viện giao diện người dùng, đó là: core (lõi), client (ứng dụng) và provider (nhà cung cấp). Thư viện lõi cung cấp các giao diện mà thư viện ứng dụng và thư viện nhà cung cấp sử dụng. Nhà cung cấp giao diện người dùng (thường là SDK) sẽ dựa vào thư viện nhà cung cấp và người dùng giao diện người dùng (thường là nhà xuất bản) sẽ dựa vào thư viện ứng dụng. Thư viện ứng dụng và thư viện nhà cung cấp, cùng với nhau tạo thành kênh phụ cần thiết để tạo và duy trì một phiên giao diện người dùng.

Các API

Sau đây là các API dùng để trình bày giao diện người dùng trong Thời gian chạy SDK:

SandboxedUiAdapter: Do SDK tạo, cung cấp cách thức để lấy nội dung sẽ hiển thị trong giao diện người dùng của nhà xuất bản.

SandboxedSdkView: Do nhà xuất bản tạo, đây là vùng chứa lưu giữ nội dung có được thông qua SandboxedUiAdapter.

Session: Do SDK tạo để phản hồi SandboxedUiAdapter.openSession(). Đại diện cho một lệnh gọi phiên giao diện người dùng. API này hình thành nên điểm kết thúc của SDK trong đường hầm liên lạc giữa SDK và nhà xuất bản, đồng thời nhận thông báo về các thay đổi trong SandboxedSdkView, chẳng hạn như việc tách cửa sổ, đổi kích thước hoặc thay đổi cấu hình.

SessionClient: Do thư viện ứng dụng tạo, API này hình thành nên điểm cuối của đường hầm liên lạc giữa SDK và nhà xuất bản.

SandboxedSdkUiSessionStateChangedListener: Do nhà xuất bản tạo. Một trình nghe theo dõi các thay đổi đối với trạng thái của phiên giao diện người dùng được liên kết với SandboxedSdkView.

Hãy đọc tài liệu tham khảo về privacysandbox-ui để biết thêm thông tin chi tiết về các API này.

Luồng điều khiển

Các biểu đồ sau đây cho thấy sự tương tác giữa thư viện giao diện người dùng ứng dụng và thư viện giao diện người dùng nhà cung cấp trong nhiều trường hợp:

Sơ đồ trước cho thấy cách nhà xuất bản có thể tạo một SandboxedSdkView theo phương thức lập trình hoặc thông qua XML và đính kèm tệp đó vào SdkSandboxUiAdapter lấy từ SDK thông qua API do SDK xác định. Để quan sát tất cả các thay đổi về trạng thái giao diện người dùng, nhà xuất bản nên thêm một SandboxedSdkUiSessionStateChangedListener vào SandboxedSdkView trước khi đính kèm SdkSandboxUiAdapter.

Sơ đồ này cho thấy nếu hoạt động của nhà xuất bản xử lý các thay đổi về cấu hình, thì thư viện ứng dụng sẽ xử lý việc chuyển tiếp thay đổi về cấu hình này đến SDK như thế nào để nhà xuất bản có thể cập nhật giao diện người dùng cho phù hợp. Ví dụ: luồng này có thể được kích hoạt khi người dùng xoay thiết bị và nhà xuất bản khai báo việc xử lý các thay đổi về cấu hình trong hoạt động của họ, bằng cách đặt android:configChanges=["orientation"].

Sơ đồ này minh hoạ cách SDK có thể yêu cầu thay đổi trong vùng chứa quảng cáo bằng cách sử dụng trên SessionClient. API này được kích hoạt khi SDK muốn đổi kích thước quảng cáo và cần nhà xuất bản đổi kích thước vùng chứa quảng cáo cho phù hợp với kích thước mới. Điều này có thể xảy ra để phản hồi tương tác của người dùng, chẳng hạn như mraid.resize().

Sơ đồ này cho biết cách phiên đóng khi SandboxedSdkView bị tách ra khỏi cửa sổ. SDK cũng có thể đóng phiên bất cứ lúc nào (ví dụ: khi người dùng mất kết nối mạng) bằng cách gọi SessionClient.onSessionError().

Thứ tự Z

Thư viện giao diện người dùng ứng dụng sử dụng một SurfaceView nội bộ để lưu trữ giao diện người dùng của SDK. SurfaceView có thể sử dụng thứ tự Z để hiện giao diện người dùng ở trên cùng hoặc bên dưới cửa sổ của nhà xuất bản. Việc này được kiểm soát bằng phương thức SandboxedSdkView.orderProviderUiAboveClientUi(). Phương thức này chấp nhận một boolean setOnTop.

Khi setOnTop là true, mọi android.view.MotionEvent trên SandboxedSdkView sẽ được gửi đến SDK. Khi false, các giá trị này sẽ được gửi đến nhà xuất bản. Theo mặc định, các sự kiện chuyển động được gửi đến SDK.

Nhà xuất bản thường không cần thay đổi thứ tự Z mặc định của khung hiển thị quảng cáo. Tuy nhiên, khi hiện giao diện người dùng che phủ một quảng cáo, chẳng hạn như trình đơn thả xuống, thứ tự Z sẽ tạm thời được lật ngược từ thứ tự mặc định, sau đó được khôi phục khi thành phần giao diện người dùng che phủ được đóng. Chúng tôi đang nghiên cứu cách tự động hoá quy trình này trong thư viện giao diện người dùng ứng dụng.

Cử chỉ cuộn

Khi giao diện người dùng quảng cáo được sắp xếp theo thứ tự Z ở phía trên cửa sổ nhà xuất bản, MotionEvents từ giao diện người dùng quảng cáo sẽ được gửi đến SDK. Các cử chỉ cuộn và hất khởi tạo trên giao diện người dùng của quảng cáo sẽ được xử lý đặc biệt:

1. Các cử chỉ hất và cuộn theo chiều dọc được gửi đến và xử lý bởi vùng chứa của nhà xuất bản. Điều này mang lại trải nghiệm tốt cho người dùng khi vùng chứa của nhà xuất bản mà giao diện người dùng của quảng cáo đặt trong đó có thể cuộn theo chiều dọc. Bạn không cần phải làm gì thêm về phần SDK hoặc nhà xuất bản.
2. Các cử chỉ hất và cuộn theo chiều ngang được gửi đến và xử lý bởi SDK. Điều này mang lại trải nghiệm tốt cho người dùng khi chính giao diện người dùng của quảng cáo có thể cuộn theo chiều ngang (chẳng hạn như băng chuyền quảng cáo).

Hướng dẫn triển khai

SDK nên triển khai những nội dung sau:

• SandboxedUiAdapter: Mã này được trả về cho nhà xuất bản để phản hồi một API do SDK xác định, chẳng hạn như loadAd. Phương thức openSession() của thao tác này nên được sử dụng để tạo một yêu cầu quảng cáo đến máy chủ của SDK và chuẩn bị chế độ xem quảng cáo cho yêu cầu đó.
• Session**: API này được trả về để phản hồi giá trị Cuộc gọi SandboxedUiAdapter.openSession. Nó cung cấp một cách để khách hàng để lấy giao diện người dùng quảng cáo và thông báo cho SDK về các thay đổi đối với API này. Bạn phải triển khai mọi phương thức Session tại đây.

Nhà xuất bản cần thực hiện những việc sau:

1. Tạo một SandboxedSdkView thông qua XML hoặc theo phương thức lập trình.
2. Đính kèm một SandboxedSdkUiSessionStateChangedListener vào SandboxedSdkView để quan sát các thay đổi trong giao diện người dùng.
3. Đính kèm một SandboxedUiAdapter do SDK cung cấp vào SandboxedSdkView.
4. Thêm SandboxedSdkView vào cửa sổ như bình thường và để thư viện ứng dụng đảm nhiệm việc tạo và duy trì phiên giao diện người dùng bằng SDK.
5. Tại các thời điểm thích hợp, phản ứng với những thay đổi về trạng thái do SandboxedSdkUiSessionChangedListener báo cáo. Ví dụ: nếu SDK đóng phiên đột ngột, thì nhà xuất bản có thể thay thế SandboxedSdkView bằng một hình ảnh tĩnh hoặc xoá khung hiển thị đó khỏi hệ phân cấp khung hiển thị của họ.
6. Khi thực hiện các hoạt động chuyển đổi có thể che phủ giao diện người dùng của quảng cáo, chẳng hạn như trình đơn thả xuống, hãy tạm thời đặt orderProviderUiAboveClientUi thành false để đặt giao diện người dùng quảng cáo ở bên dưới cửa sổ của nhà xuất bản. Sau khi trình đơn thả xuống đóng, hãy gọi orderProviderUiAboveClientUi thành true.

Tương lai của các API nền tảng

Sau khi các thư viện giao diện người dùng chuyển sang giai đoạn Beta, chúng tôi dự định sẽ không dùng các API nền tảng thời gian chạy SDK liên quan đến việc trình bày giao diện người dùng nữa, cụ thể là SdkSandboxManager.requestSurfacePackage() và SandbxedSdkProvider.getView().

Câu hỏi mở

1. Có trường hợp sử dụng giao diện người dùng quảng cáo phổ biến nào khác mà các thư viện giao diện người dùng sẽ tự động xử lý không?
2. Bạn sử dụng khung giao diện người dùng nào để hiện giao diện người dùng của quảng cáo, bạn có lường trước được các vấn đề khi tích hợp thư viện giao diện người dùng với các khung này không?
3. Giao diện người dùng quảng cáo có thể cuộn được đặt trong một vùng chứa có thể cuộn của nhà xuất bản có phải là trường hợp sử dụng phổ biến đối với bạn không? Trong trường hợp này, hướng cuộn của giao diện người dùng quảng cáo và vùng chứa là thế nào? Bạn mong đợi hành vi nào khi người dùng bắt đầu cuộn trên giao diện người dùng của quảng cáo?