Hỗ trợ dàn xếp trong Thời gian chạy SDK

Dàn xếp là một cách phổ biến để các nền tảng quảng cáo bên bán cung cấp dịch vụ quản lý lợi nhuận. Trong quy trình dàn xếp, SDK dàn xếp ("trình dàn xếp") sẽ gọi nhiều mạng quảng cáo ("được dàn xếp" hoặc "được dàn xếp") để lấy quảng cáo phù hợp nhất cho một vị trí nhất định. Trong một số trường hợp, cả trình dàn xếp và mạng quảng cáo mà trình dàn xếp gọi đều cần SDK của chúng phải có trên thiết bị và tương tác.

Tài liệu này trình bày các thay đổi chính đối với quy trình dàn xếp trong Thời gian chạy SDK. Bài viết này đề cập đến các chủ đề sau:

• Sự khác biệt giữa quy trình dàn xếp trước đây và tính năng hỗ trợ dàn xếp Thời gian chạy SDK hiện tại
• Thiết lập các hành động cho quy trình dàn xếp trong Thời gian chạy SDK và các giai đoạn chuyển đổi khác nhau
• Hướng dẫn về cách xử lý các trường hợp không phải tất cả SDK đều đã di chuyển sang Thời gian chạy

Hỗ trợ cho Quảng cáo được dàn xếp trong Thời gian chạy SDK có trong AGP 8.5 và trong các phiên bản sau của thư viện Jetpack Thời gian chạy SDK:

Thư viện Androidx	Phiên bản
androidx.privacysandbox.activity	1.0.0-alpha01
androidx.privacysandbox.sdkruntime	1.0.0-alpha13
androidx.privacysandbox.tools	1.0.0-alpha08
androidx.privacysandbox.ui	1.0.0-alpha09

Bảng thuật ngữ

Các thuật ngữ sau đây là chìa khoá để hiểu được tính năng dàn xếp trong Thời gian chạy SDK:

• SDK hỗ trợ thời gian chạy (SDK RE): Một SDK được tạo để chạy trong môi trường Thời gian chạy SDK và giao tiếp với ứng dụng thông qua giao tiếp liên quy trình (IPC).
• SDK nhận biết thời gian chạy (RA SDK): Một SDK không hỗ trợ thời gian chạy, được liên kết với ứng dụng một cách tĩnh, có thể chứa mã SDK hiện có cũng như mã mới để gọi vào SDK hỗ trợ thời gian chạy.
• SDK trong ứng dụng: Một SDK chạy được liên kết tĩnh với ứng dụng và không nhận biết được Thời gian chạy SDK. Đây có thể là một mạng quảng cáo chưa chuyển sang Thời gian chạy SDK hoặc bộ chuyển đổi tuỳ chỉnh của nhà xuất bản.
• Trình dàn xếp: SDK dàn xếp quảng cáo cung cấp dịch vụ dàn xếp trên thiết bị bằng cách tương tác với các SDK mạng quảng cáo khác.
• Mediatee: SDK mạng quảng cáo được Trình dàn xếp gọi để cung cấp và hiển thị quảng cáo.
• Bộ chuyển đổi dàn xếp: Các SDK do SDK dàn xếp sử dụng để cung cấp dịch vụ biên dịch giao diện API nhằm tương tác với nhiều SDK dàn xếp, thường do trình dàn xếp cung cấp. Các biến này có thể nhận biết được thời gian chạy hoặc không nhận biết được thời gian chạy.

Quy trình dàn xếp thông thường

Nếu SDK của bạn cần hỗ trợ các trường hợp sử dụng dàn xếp trong Thời gian chạy SDK, bạn sẽ cần triển khai một số thay đổi. Phần này xem xét các thành phần chính của quy trình dàn xếp để chúng ta có thể giải quyết những thay đổi cần thiết đối với bên dàn xếp và bên được dàn xếp.

Các luồng mà chúng tôi mô tả đại diện cho phiên bản đơn giản của tính năng dàn xếp trên thiết bị với nhiều SDK mạng quảng cáo, đồng thời là cơ sở để thảo luận về những thay đổi cần thiết để giúp hành trình dàn xếp tương thích với Thời gian chạy SDK.

Do sự khác biệt trong việc triển khai quy trình dàn xếp, chúng tôi tập trung vào hai quy trình chính sau:

• Khởi chạy (bao gồm cả việc khám phá mạng quảng cáo và giao tiếp)
• Bản trình bày giao diện người dùng (UI) của quảng cáo

Khởi chạy

Dưới đây là quy trình khởi chạy, khám phá mạng quảng cáo và giao tiếp chuẩn:

1. Ứng dụng khách khởi tạo trình dàn xếp
2. Trình dàn xếp phát hiện và khởi chạy các đối tượng dàn xếp và bộ chuyển đổi có liên quan
3. Trình dàn xếp sử dụng các bộ chuyển đổi để giao tiếp với từng bên được dàn xếp
4. Ứng dụng khách yêu cầu trình dàn xếp tải quảng cáo
5. Ứng dụng khách yêu cầu trình dàn xếp hiển thị quảng cáo này

Lưu ý: Quy trình này giả định rằng ứng dụng khách có phần phụ thuộc trên SDK dàn xếp, SDK của bên được dàn xếp và bộ chuyển đổi dàn xếp, đồng thời ứng dụng khách được tạo bằng các phần phụ thuộc đó.

Bản trình bày giao diện người dùng của quảng cáo

Khi hiển thị quảng cáo sau yêu cầu cuối cùng ở bước trước, quy trình sẽ phụ thuộc vào loại quảng cáo:

Quảng cáo biểu ngữ	Quảng cáo toàn màn hình	Quảng cáo gốc
SDK dàn xếp tạo một Khung hiển thị quảng cáo, bao gồm Khung hiển thị quảng cáo của bên dàn xếp chiến thắng. Có thể cũng đặt trình nghe trên Chế độ xem này hoặc tự động làm mới quảng cáo (sử dụng cùng một hoặc một đối tượng trung gian khác).	SDK dàn xếp yêu cầu quảng cáo toàn màn hình từ bên được dàn xếp, từ đó bắt đầu một Hoạt động.	Nhà xuất bản quản lý việc xử lý và tăng cường chế độ xem bằng các thành phần do SDK dàn xếp trả về.

Quy trình dàn xếp trong Thời gian chạy SDK

Cách thức hoạt động của tính năng dàn xếp bên trong Thời gian chạy SDK sẽ khác nhau tuỳ thuộc vào việc bên được dàn xếp có hỗ trợ thời gian chạy hay không. Dựa trên điều này, chúng ta có thể có các trường hợp sau:

• Cả trình dàn xếp và đối tượng được dàn xếp đều nằm trong Thời gian chạy SDK: Đối tượng được dàn xếp RE
• Trình dàn xếp nằm trong Thời gian chạy SDK và đối tượng được dàn xếp nằm trong ứng dụng: Đối tượng được dàn xếp trong ứng dụng

RE Mediatee

Sơ đồ cấu trúc sau đây cho thấy thông tin tổng quan cấp cao về hoạt động tương tác của SDK hỗ trợ thời gian chạy (RE) và SDK nhận biết thời gian chạy (RA) của trình dàn xếp, bộ chuyển đổi dàn xếp RE và SDK RE của bên được dàn xếp.

Bộ chuyển đổi dàn xếp cần phải nằm trong cùng một quy trình với bên trung gian mà chúng đang giao tiếp, vì vậy, các bộ chuyển đổi này cũng sẽ phải di chuyển sang Thời gian chạy SDK.

**Hình 1.** Cả trình dàn xếp và đối tượng được dàn xếp đều là SDK RE.

Khởi chạy

Khi xem xét việc khởi chạy, khám phá và giao tiếp của cả trình dàn xếp và đối tượng được dàn xếp hỗ trợ thời gian chạy, quy trình sẽ tuân theo các bước sau:

1. Ứng dụng (hoặc SDK RA) tải và khởi chạy SDK dàn xếp bằng cách sử dụng SdkSandboxManager#loadSdk.
2. Trong quá trình khởi chạy, SDK dàn xếp sẽ tải và khởi chạy mọi đối tượng dàn xếp bắt buộc trong Thời gian chạy SDK bằng SdkSandboxController#loadSdk.
3. SDK RE có thể khám phá tất cả SDK đã tải trong Thời gian chạy bằng cách gọi SdkSandboxController#getSandboxedSdks.

**Hình 2.** Quy trình để khởi chạy một đối tượng dàn xếp RE.

Lưu ý: Sử dụng các lớp Trình quản lý thời gian chạy và Trình điều khiển *Compat để đảm bảo rằng SDK hỗ trợ thời gian chạy của bạn có khả năng tương thích ngược.

Bản trình bày giao diện người dùng của quảng cáo

Phần sau đây trình bày về việc tải biểu ngữ và quảng cáo toàn màn hình từ một mediatee RE.

Quảng cáo biểu ngữ RE Mediatee

Khi ứng dụng yêu cầu tải quảng cáo biểu ngữ, quy trình hoàn tất quá trình kết xuất sẽ diễn ra như sau:

1. Bên dàn xếp sẽ chọn bên được dàn xếp chiến thắng cho quảng cáo này.
2. Trình dàn xếp lấy SandboxedUiAdapter từ đối tượng được dàn xếp.
3. Trình dàn xếp chuyển tiếp UiAdapter đến ứng dụng.

**Hình 3.** Quy trình hoàn tất việc hiển thị quảng cáo biểu ngữ từ một bên trung gian RE.

Tìm hiểu thêm về cách sử dụng SandboxedUiAdapter và Thư viện giao diện người dùng Thời gian chạy SDK.

Lớp phủ cho quảng cáo biểu ngữ

Nếu muốn thêm lớp phủ vào quảng cáo, bên dàn xếp sẽ phải sửa đổi quy trình như sau:

1. Trình dàn xếp tạo một bố cục có lớp phủ và SandboxedSdkView.
2. Bên dàn xếp sẽ chọn bên được dàn xếp chiến thắng cho quảng cáo này.
3. Trình dàn xếp lấy SandboxedUiAdapter từ bên được dàn xếp.
4. Trình dàn xếp đặt UiAdapter của đối tượng được dàn xếp thành SandboxedSdkView.
5. Trình dàn xếp chia sẻ thành phần hiển thị đã điền sẵn với ứng dụng.

Luồng để phủ một thành phần hiển thị lên quảng cáo biểu ngữ thu được từ RE Mediatee.

Quảng cáo toàn màn hình RE Mediatee

Khi ứng dụng yêu cầu tải quảng cáo toàn màn hình, quy trình sẽ tuân theo các bước sau:

1. Ứng dụng (hoặc SDK RA) chuyển một SdkActivityLauncher đến trình dàn xếp cùng với yêu cầu tải quảng cáo.
   1. Ứng dụng có thể hạn chế việc tạo hoạt động bằng cách sử dụng một thuộc tính.
2. Bên dàn xếp sẽ chọn bên được dàn xếp chiến thắng cho quảng cáo này.
3. Phương thức dàn xếp yêu cầu bên được dàn xếp tải quảng cáo, chuyển SdkActivityLauncher từ ứng dụng.
4. Đối tượng trung gian đăng ký một trình xử lý hoạt động và nhận mã thông báo nhận dạng cho hoạt động đã đăng ký.
5. Bên trung gian sử dụng SdkActivityLauncher để yêu cầu bắt đầu một hoạt động bằng mã thông báo này.
6. Nếu thuộc tính của ứng dụng khách cho phép, Thời gian chạy SDK sẽ bắt đầu hoạt động này trong quy trình chuyên dụng.

**Hình 4.** Sơ đồ quy trình minh hoạ cách tải quảng cáo toàn màn hình được dàn xếp từ RE Mediatee.

Lưu ý: Tất cả sự kiện trong vòng đời của hoạt động đều có sẵn cho đối tượng trung gian bằng cách sử dụng ActivityHolder mà đối tượng trung gian đó sử dụng khi đăng ký trình xử lý hoạt động.

Tìm hiểu thêm về tính năng hỗ trợ Hoạt động cho quảng cáo toàn màn hình trong Thời gian chạy SDK.

Mediatee trong ứng dụng

Sơ đồ cấu trúc sau đây cho thấy thông tin tổng quan cấp cao về hoạt động tương tác của SDK RE và RA của trình dàn xếp, của các bộ chuyển đổi dàn xếp không nhận biết được Thời gian chạy SDK và SDK của các bên được dàn xếp được liên kết tĩnh với ứng dụng (cũng không nhận biết được thời gian chạy).

**Hình 5.** Đối tượng trung gian được liên kết tĩnh với ứng dụng, ngay cả khi biết về SDK RE.

Khởi chạy

Vì trong trường hợp này, các đối tượng trung gian được liên kết tĩnh với ứng dụng và chưa được di chuyển sang Thời gian chạy SDK, nên SDK hỗ trợ thời gian chạy của đối tượng trung gian phải có quy trình để đăng ký các đối tượng đó.

Bạn có thể truy cập vào thông tin đăng ký này bằng API của trình dàn xếp, nhưng thông tin chi tiết về cách triển khai sẽ do từng trình dàn xếp quyết định. Chúng ta gọi API này là MediationSandboxedSdk#registerInAppMediatee.

Khi xem xét việc khởi chạy, khám phá và giao tiếp của SDK dàn xếp RE và SDK được dàn xếp trong ứng dụng, quy trình sẽ tuân theo các bước sau:

1. Ứng dụng tải và khởi chạy SDK nhận biết thời gian chạy của trình dàn xếp.
2. SDK RA của bên dàn xếp:
   1. Khởi chạy SDK RE của trình dàn xếp bằng SdkSandboxManager#loadSdk.
   2. Khởi chạy tất cả SDK trung gian trong ứng dụng.
   3. Khám phá và đăng ký các SDK trung gian trong ứng dụng bằng API do SDK RE cung cấp, MediationSandboxedSdk#registerInAppMediate.

Ngoài việc đăng ký tất cả SDK được dàn xếp trong ứng dụng, SDK RE của trình dàn xếp có thể khám phá tất cả SDK được tải trong Thời gian chạy SDK bằng cách sử dụng SdkSandboxController#getSandboxedSdks.

**Hình 6.** Xin lưu ý rằng chúng ta sử dụng API của trình dàn xếp được đề xuất để đăng ký tham chiếu đến các đối tượng được dàn xếp trong ứng dụng.

Bản trình bày giao diện người dùng của quảng cáo

Phần sau đây trình bày cách tải biểu ngữ và quảng cáo toàn màn hình từ một mediatee trong ứng dụng.

Quảng cáo biểu ngữ dàn xếp trong ứng dụng

Khi ứng dụng yêu cầu tải quảng cáo biểu ngữ, quy trình hoàn tất quá trình kết xuất sẽ diễn ra như sau:

1. SDK nhận biết thời gian chạy của trình dàn xếp sẽ chuyển tiếp yêu cầu của ứng dụng đến SDK hỗ trợ thời gian chạy.
2. SDK RE của trình dàn xếp sẽ chọn đối tượng dàn xếp có liên quan.
3. SDK RE của trình dàn xếp truy xuất tệp tham chiếu đến bên được dàn xếp và yêu cầu tải quảng cáo thông qua SDK RA.
4. SDK RA lấy một Khung hiển thị từ bên trung gian trong ứng dụng.
5. SDK RA tạo một SandboxedUiAdapter cho Chế độ xem mà nó nhận được.
6. SDK RA chuyển tiếp UiAdapter đến SDK RE.
7. SDK RE chuyển tiếp UiAdapter đến ứng dụng.

Thận trọng: Vì SandboxedUiAdapter này được nhận từ quy trình của ứng dụng, nên bạn không nên thêm lớp phủ vào Chế độ xem này vì có thể dẫn đến các vấn đề về độ trễ, hiệu suất và hành vi.

**Hình 7.** Xin lưu ý rằng trình dàn xếp không được phủ các chế độ xem lên V1 khi lấy chế độ xem đó từ một bên được dàn xếp trong ứng dụng.

Quảng cáo toàn màn hình do bên trung gian cung cấp trong ứng dụng

Khi ứng dụng yêu cầu tải quảng cáo toàn màn hình, quy trình sẽ tuân theo các bước sau:

1. Ứng dụng chuyển một SdkActivityLauncher đến SDK RA của trình dàn xếp cùng với yêu cầu tải quảng cáo.
   1. Ứng dụng có thể hạn chế việc tạo hoạt động bằng cách sử dụng một thuộc tính.
2. SDK RA của trình dàn xếp chuyển tiếp yêu cầu của ứng dụng đến SDK RE.
3. SDK RE của trình dàn xếp:
   1. Chọn đối tượng dàn xếp có liên quan.
   2. Truy xuất tệp tham chiếu đến đối tượng dàn xếp trong ứng dụng.
   3. Yêu cầu tải quảng cáo thông qua SDK RA.
4. SDK RA yêu cầu bên dàn xếp tải quảng cáo.
5. Đối tượng trung gian khởi động trực tiếp hoạt động. Tính năng đối số của ứng dụng sẽ không được thực hiện.

**Hình 8.** Biến quan hệ sẽ bị bên trung gian trong ứng dụng bỏ qua.

Lưu ý: Tất cả sự kiện xung quanh hoạt động đều có sẵn cho bên trung gian như trước Thời gian chạy SDK.

Tương tác và chia sẻ ý kiến phản hồi

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à cải thiện các tính năng của công cụ này. Báo lỗi để đưa ra ý kiến phản hồi.