Cách Triển Khai PrivacyInfo.xcprivacy Cho Ứng Dụng và SDK iOS

Cách triển khai PrivacyInfo.xcprivacy cho ứng dụng iOS? Việc triển khai PrivacyInfo.xcprivacy yêu cầu thêm một tệp kê khai quyền riêng tư hợp lệ vào mục tiêu ứng dụng hoặc SDK của bạn, khai báo các mã lý do đã được phê duyệt cho bất kỳ API theo Mục Đích Bắt Buộc nào được sử dụng (chẳng hạn như User Defaults hoặc System Boot Time), và xác minh rằng các phần phụ thuộc của bên thứ ba đáp ứng các yêu cầu về tệp kê khai quyền riêng tư và chữ ký áp dụng cho hình thức phân phối của chúng.

Tệp Kê Khai Quyền Riêng Tư (PrivacyInfo.xcprivacy) là một tệp danh sách thuộc tính chuẩn hóa được đóng gói bên trong các ứng dụng iOS và SDK của bên thứ ba, nhằm khai báo các danh mục thu thập dữ liệu, cấu hình miền theo dõi và các lý do được phê duyệt để truy cập các API theo Mục Đích Bắt Buộc do Apple chỉ định. Bắt đầu từ ngày 1 tháng 5 năm 2024, các ứng dụng gửi lên App Store Connect phải bao gồm các lý do được phê duyệt cho các API theo Mục Đích Bắt Buộc được sử dụng bởi mã của ứng dụng, bao gồm cả mã SDK của bên thứ ba áp dụng.

Hiểu Về Các Yêu Cầu Tệp Kê Khai Quyền Riêng Tư Của Apple Cho SDK iOS

Kiến Trúc Của Tệp Kê Khai Quyền Riêng Tư: Tệp Kê Khai Ứng Dụng Chính So Với Tệp Kê Khai SDK Nhúng

Khung tệp kê khai quyền riêng tư của Apple thiết lập một mô hình minh bạch mô-đun xuyên suốt chuỗi cung ứng phần mềm iOS. Thay vì yêu cầu ứng dụng chủ phải tự kiểm tra và khai báo các chi tiết thực thi bên trong của mọi thư viện được nhập, Apple chia việc quản trị quyền riêng tư thành các lớp rõ ràng:

• Tệp Kê Khai Ứng Dụng Chính: Bao gồm việc thu thập dữ liệu bên thứ nhất, các miền theo dõi cấp ứng dụng và các API theo Mục Đích Bắt Buộc được gọi trực tiếp bởi mã mục tiêu ứng dụng chính.
• Tệp Kê Khai SDK Nhúng: Các khai báo API theo Mục Đích Bắt Buộc phải thuộc sở hữu của ứng dụng hoặc mã SDK của bên thứ ba sử dụng các API đó. Đối với các tệp thực thi và thư viện động, gói chứa tệp thực thi hoặc thư viện đó phải bao gồm tệp kê khai quyền riêng tư có liên quan; SDK của bên thứ ba không thể dựa vào tệp kê khai của ứng dụng chủ để báo cáo việc sử dụng API theo Mục Đích Bắt Buộc của SDK đó.
• Tổng Hợp Phụ Thuộc Tự Động: Khi một ứng dụng được lưu trữ trong Xcode 15 trở lên, hệ thống xây dựng sẽ duyệt qua biểu đồ phụ thuộc, phát hiện tất cả các tệp PrivacyInfo.xcprivacy được đóng gói và tổng hợp chúng thành một Báo Cáo Quyền Riêng Tư thống nhất duy nhất.

Bốn Khóa Cấu Hình Gốc

Mỗi tệp PrivacyInfo.xcprivacy được cấu trúc dưới dạng một từ điển danh sách thuộc tính XML chứa tối đa bốn khóa cấp gốc:

• NSPrivacyTracking (Boolean): Khai báo liệu ứng dụng hoặc SDK có sử dụng dữ liệu được thu thập từ ứng dụng để theo dõi theo định nghĩa Minh Bạch Về Quyền Theo Dõi Của Người Dùng (ATT) của Apple hay không.
• NSPrivacyTrackingDomains (Mảng Chuỗi): Liệt kê các miền internet mà ứng dụng hoặc SDK kết nối đến và tham gia vào hoạt động theo dõi. Nếu người dùng không cấp quyền ATT, iOS sẽ chặn các kết nối mạng đến các miền được khai báo trong mảng này. Nếu ứng dụng hoặc SDK không kết nối với các miền theo dõi, khóa này có thể được bỏ qua.
• NSPrivacyCollectedDataTypes (Mảng Từ Điển): Báo cáo các danh mục dữ liệu do Apple định nghĩa mà ứng dụng hoặc SDK thu thập về những người sử dụng ứng dụng, kèm theo thông tin liệu dữ liệu có được liên kết với danh tính người dùng hay không, có được sử dụng để theo dõi hay không và các mục đích vận hành được thu thập.
• NSPrivacyAccessedAPITypes (Mảng Từ Điển): Khai báo các API theo Mục Đích Bắt Buộc do Apple chỉ định được gọi bởi tệp nhị phân, đi kèm với các mã lý do dạng chuỗi đã được phê duyệt.

Thực Thi Tiếp Nhận App Store Connect và Chuẩn Đoán Lỗi

App Store Connect thực thi các tệp kê khai quyền riêng tư trong quá trình tiếp nhận tệp nhị phân:

• Thiếu Khai Báo API (ITMS-91053): Được kích hoạt khi tệp nhị phân được biên dịch hoặc thư viện được liên kết gọi đến một ký hiệu API theo Mục Đích Bắt Buộc, nhưng khóa danh mục tương ứng bị thiếu trong NSPrivacyAccessedAPITypes.
• Khai Báo Mã Lý Do Không Hợp Lệ: Xảy ra khi tệp kê khai khai báo một chuỗi lý do chưa được phê duyệt, bị lỗi hoặc đã lỗi thời cho một danh mục API cụ thể.
• Thiếu Tệp Kê Khai SDK Bên Thứ Ba Bắt Buộc: Được thực thi trong các tình huống gửi được xác định theo các yêu cầu SDK bên thứ ba hiện tại của Apple đối với các SDK được liệt kê, yêu cầu cả tệp kê khai quyền riêng tư và chữ ký số hợp lệ cho việc phân phối tệp nhị phân.

Các nhà phát triển tích hợp tính năng quy kết khách hàng và liên kết sâu có thể tham khảo tài liệu tích hợp SDK iOS để biết các thông số kỹ thuật liên quan đến việc khai báo tệp kê khai.

Xem Thêm: SDK iOS ──> Kiến Trúc Quy Kết Di Động

Các Danh Mục API Theo Mục Đích Bắt Buộc và Mã Lý Do Được Phê Duyệt

Năm Danh Mục API Theo Mục Đích Bắt Buộc

Theo Tài liệu kỹ thuật TN3183 của nhà phát triển Apple, Apple xác định năm danh mục API cụ thể yêu cầu mã giải trình rõ ràng trong NSPrivacyAccessedAPITypes. Các SDK di động và ứng dụng iOS thường tương tác với bốn danh mục chính:

• NSPrivacyAccessedAPICategoryUserDefaults: Truy cập cài đặt ứng dụng cục bộ thông qua UserDefaults hoặc NSUserDefaults.
• NSPrivacyAccessedAPICategorySystemBootTime: Đo lường thời gian đã trôi qua hoặc dấu thời gian bằng cách sử dụng các API khởi động hệ thống như sysctl(KERN_BOOTTIME) hoặc systemUptime.
• NSPrivacyAccessedAPICategoryDiskSpace: Kiểm tra dung lượng hệ thống tệp thông qua statfs, statvfs hoặc volumeAvailableCapacityKey.
• NSPrivacyAccessedAPICategoryFileTimestamp: Kiểm tra ngày tạo hoặc sửa đổi tệp thông qua stat, getattrlist hoặc contentModificationDateKey.
• NSPrivacyAccessedAPICategoryActiveKeyboards: Kiểm tra các tiện ích mở rộng bàn phím tùy chỉnh đang hoạt động (chủ yếu được sử dụng bởi các tiện ích bàn phím chuyên dụng).

Bản Đồ Mã Lý Do Đã Được Phê Duyệt Cho Các Trường Hợp Sử Dụng SDK Phổ Biến

Bảng dưới đây tập trung vào các danh mục thường gặp trong các SDK di động đa năng; hãy tham khảo tài liệu hiện tại của Apple để biết danh sách lý do đầy đủ, bao gồm Bàn Phím Hoạt Động. Để tuân thủ các nguyên tắc của Apple, các nhà phát triển phải chọn mã lý do khớp chính xác với việc sử dụng dữ liệu thời gian chạy thực tế của họ:

Xây Dựng Một Tờ Khai Thuộc Tính PrivacyInfo.xcprivacy Mẫu

Cấu Hình Các Loại Thu Thập Dữ Liệu

Mảng NSPrivacyCollectedDataTypes báo cáo các danh mục dữ liệu do Apple định nghĩa mà ứng dụng hoặc SDK thu thập về những người sử dụng ứng dụng, kèm theo thông tin liệu dữ liệu có được liên kết với danh tính người dùng hay không, có được sử dụng để theo dõi hay không và các mục đích vận hành được thu thập:

• NSPrivacyCollectedDataType: Định danh chuỗi chuẩn của Apple (ví dụ: NSPrivacyCollectedDataTypeDeviceID).
• NSPrivacyCollectedDataTypeLinked: Giá trị boolean cho biết liệu dữ liệu có được liên kết với danh tính của một người dùng cụ thể hay không.
• NSPrivacyCollectedDataTypeTracking: Giá trị boolean cho biết liệu dữ liệu có được sử dụng để theo dõi trên các ứng dụng hay không.
• NSPrivacyCollectedDataTypePurposes: Một mảng các chuỗi mục đích tiêu chuẩn (ví dụ: NSPrivacyCollectedDataTypePurposeAnalytics).

Khai Báo Các Miền Theo Dõi

Nếu SDK hoặc ứng dụng tham gia vào hoạt động theo dõi theo định nghĩa của ATT, tất cả các miền theo dõi tương ứng phải được khai báo dưới mục NSPrivacyTrackingDomains. Nếu người dùng không cấp quyền theo dõi, iOS sẽ chặn các kết nối mạng tới các miền đã khai báo. Nếu ứng dụng hoặc SDK không tham gia vào hoạt động theo dõi, NSPrivacyTracking phải được đặt thành false và NSPrivacyTrackingDomains có thể được bỏ qua.

Cấu hình danh sách thuộc tính dưới đây minh họa một lược đồ PrivacyInfo.xcprivacy mẫu. Chỉ bao gồm các danh mục và lý do phản ánh đúng việc triển khai thực tế của ứng dụng bạn:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSPrivacyTracking</key>
    <false/>
    <key>NSPrivacyCollectedDataTypes</key>
    <array>
        <dict>
            <key>NSPrivacyCollectedDataType</key>
            <string>NSPrivacyCollectedDataTypeDeviceID</string>
            <key>NSPrivacyCollectedDataTypeLinked</key>
            <false/>
            <key>NSPrivacyCollectedDataTypeTracking</key>
            <false/>
            <key>NSPrivacyCollectedDataTypePurposes</key>
            <array>
                <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
                <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
            </array>
        </dict>
    </array>
    <key>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>CA92.1</string>
            </array>
        </dict>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategorySystemBootTime</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>35F9.1</string>
            </array>
        </dict>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>E174.1</string>
            </array>
        </dict>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>C617.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Khắc Phục Lỗi Ký Mã Gói Tài Nguyên CocoaPods

Nguyên Nhân Gốc Rễ: Lỗi Thất Bại Ký Mã Gói Tài Nguyên Trong Xcode 15 và 16

Khi tích hợp các phần phụ thuộc thông qua CocoaPods trong Xcode 15 hoặc 16, các nhà phát triển thường xuyên gặp phải tình trạng dừng biên dịch:

Signing for "libOpoInstallSDK-OPPrivacy" requires a development team. Select a development team in the Signing & Capabilities editor.

Lỗi bản dựng này là vấn đề tích hợp giữa Xcode và CocoaPods:

• Thư viện tĩnh .a truyền thống không thể trực tiếp chứa các tài nguyên như PrivacyInfo.xcprivacy. Apple khuyến nghị đóng gói mã SDK tĩnh và tài nguyên lại với nhau bên trong một khuôn khổ tĩnh (static framework).
• Một số cấu hình tích hợp CocoaPods thay vào đó tạo ra các mục tiêu gói tài nguyên riêng biệt để phân phối tài nguyên đi kèm với các thư viện tĩnh.
• Một số mục tiêu gói tài nguyên do CocoaPods tạo ra có thể kế thừa các cấu hình ký số khiến các bản dựng Xcode bị dừng lại và yêu cầu một nhóm phát triển. Đây là vấn đề tích hợp hệ thống xây dựng thay vì là một yêu cầu về lược đồ của PrivacyInfo.xcprivacy.

Áp Dụng Các Giải Pháp Thay Thế Hệ Thống Xây Dựng Mục Tiêu Trong Podfile

Để giải quyết lỗi này trên các bản dựng tự động, các nhà phát triển có thể sử dụng một móc nối post_install có phạm vi trong Podfile của dự án. Vì đây là một giải pháp thay thế hệ thống xây dựng cho các gói tài nguyên không thực thi được, các nhóm nên giới hạn phạm vi cho các mục tiêu gói bị ảnh hưởng cụ thể hoặc xác minh các phần phụ thuộc bị ảnh hưởng trước khi áp dụng thay đổi trên toàn cục.

Đoạn mã Ruby dưới đây minh họa cách lặp qua các mục tiêu CocoaPods và vô hiệu hóa việc ký trên các mục tiêu gói tài nguyên được chỉ định:

post_install do |installer|
  # Chỉ định các mục tiêu gói tài nguyên không thực thi gặp lỗi ký mà không có nhóm phát triển
  target_bundle_names = [
    'libOpoInstallSDK-OPPrivacy'
  ]

  installer.pods_project.targets.each do |target|
    if target.respond_to?(:product_type) &&
       target.product_type == "com.apple.product-type.bundle" &&
       target_bundle_names.include?(target.name)
      target.build_configurations.each do |config|
        # Loại bỏ yêu cầu ký mã khỏi các gói tài nguyên không thực thi được chỉ định
        config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
        config.build_settings['CODE_SIGN_IDENTITY'] = ''
      end
    end
  end
end

Kiểm Tra và Tạo Báo Cáo Quyền Riêng Tư Tổng Hợp Trong Xcode

Tạo Báo Cáo Quyền Riêng Tư Thống Nhất Thông Qua Xcode Archive Organizer

Để xác minh rằng tất cả các mục tiêu bên thứ nhất và các phần phụ thuộc của bên thứ ba được khai báo đúng cách trước khi gửi tệp nhị phân:

1. Mở dự án của bạn trong Xcode 15 trở lên.
2. Chọn Product > Archive để tạo bản lưu trữ phát hành.
3. Trong Xcode Organizer, nhấp chuột phải (hoặc nhấn giữ Control và nhấp) vào bản lưu trữ và chọn Generate Privacy Report.
4. Lưu và kiểm tra báo cáo PDF được tạo để xác nhận rằng tất cả các API theo Mục Đích Bắt Buộc, danh mục dữ liệu và tệp kê khai SDK của bên thứ ba hiển thị chính xác.

Phân Tích Tĩnh Dòng Lệnh: Quét Heuristic Trước Khi Gửi

Các nhóm phát triển có thể thực hiện kiểm tra heuristic trước khi gửi bên trong các quy trình tích hợp liên tục (CI/CD) bằng cách quét các tệp nhị phân đã biên dịch để tìm các ký hiệu bị hạn chế bằng nm và otool:

# Quét tệp nhị phân ứng dụng đã giải nén để tìm các ký hiệu API theo Mục Đích Bắt Buộc tiềm năng
nm -u /path/to/Payload/YourApp.app/YourApp | grep -E 'sysctl|statfs|statvfs|getattrlist|NSUserDefaults'

# Kiểm tra các khung nhúng và gói để tìm tệp kê khai PrivacyInfo.xcprivacy
find /path/to/Payload/YourApp.app -name "PrivacyInfo.xcprivacy"

Sự hiện diện của ký hiệu tự nó không xác định lý do được phê duyệt nào được áp dụng; hãy xem xét đường dẫn gọi thực tế và trường hợp sử dụng trước khi sửa đổi tệp kê khai. Các nhóm phải sử dụng tính năng Generate Privacy Report của Xcode và các bước kiểm tra trước của App Store Connect để xác minh có thẩm quyền.

Ma Trận Chuẩn Đoán: Nguyên Nhân Gốc Rễ Của Việc Từ Chối Tệp Kê Khai Quyền Riêng Tư Trên App Store

Tóm Tắt và Khung Quyết Định

Khung Tệp Kê Khai Quyền Riêng Tư của Apple thực thi tính minh bạch trên toàn bộ chuỗi cung ứng phần mềm iOS. Việc đảm bảo các lần gửi App Store mượt mà yêu cầu các nhóm phát triển phải kiểm toán mã bên thứ nhất để sử dụng API theo Mục Đích Bắt Buộc, xác minh rằng các phần phụ thuộc SDK của bên thứ ba đáp ứng các yêu cầu tệp kê khai quyền riêng tư áp dụng cho việc sử dụng API của chúng và quản lý việc ký gói tài nguyên CocoaPods một cách phù hợp.

Đối với các khai báo tệp kê khai quyền riêng tư dành riêng cho sản phẩm, hãy xem lại tài liệu OpoInstall và so sánh tệp kê khai đã xuất với quá trình tích hợp thực tế của ứng dụng cũng như các yêu cầu hiện tại của Apple.

Tài Liệu Liên Quan

• Khái niệm: Tệp Kê Khai Quyền Riêng Tư, API theo Mục Đích Bắt Buộc, Ký Mã Gói Tài Nguyên, Báo Cáo Quyền Riêng Tư, Tuân Thủ App Store

• Công nghệ: Xcode 15+, Trình Quản Lý Phụ Thuộc CocoaPods, Swift Package Manager, SDK iOS OpoInstall

• Tiêu chuẩn: Thông Số Kỹ Thuật Tệp Kê Khai Quyền Riêng Tư Của Apple, Nguyên Tắc Đánh Giá App Store Mục 5.1.1

• API & Cấu hình: PrivacyInfo.xcprivacy, NSPrivacyAccessedAPITypes, Mốc Nối post_install Của Podfile

Tài Liệu Chính Thức

• Tài Liệu Nhà Phát Triển Apple Về Việc Mô Tả Sử Dụng API Theo Mục Đích Bắt Buộc

• Tài Liệu Nhà Phát Triển Apple Về Các Tệp Kê Khai Quyền Riêng Tư

• Tài Liệu Nhà Phát Triển Apple Về Các Yêu Cầu SDK Bên Thứ Ba Sắp Tới

• Nguyên Tắc Đánh Giá App Store Của Apple Mục 5.1.1