Privacy Manifest — định nghĩa, tệp PrivacyInfo.xcprivacy và yêu cầu

Privacy Manifest là gì?

Privacy Manifest là tệp PrivacyInfo.xcprivacy ở định dạng property list (XML) khai báo loại dữ liệu mà ứng dụng thu thập và tại sao nó sử dụng các API nhất định. Apple đã giới thiệu tệp kê khai như một phần của sáng kiến tăng cường minh bạch quyền riêng tư, tương tự Privacy Nutrition Label, nhưng ở cấp độ mã và tệp nhị phân.

Mục đích chính của tệp kê khai là ghi lại việc sử dụng cái gọi là Required Reason API. Đây là những loại API có thể được sử dụng để lấy dấu vân tay thiết bị (fingerprinting), do đó mỗi lần sử dụng phải kèm theo khai báo lý do cụ thể từ danh sách được Apple phê duyệt.

Từ ngày 1 tháng 5 năm 2024, Apple từ chối các bản dựng không chứa Privacy Manifest. Điều này áp dụng cho cả mục tiêu chính của ứng dụng và tất cả SDK cũng như phụ thuộc được nhúng. Theo WWDC 2023, tệp kê khai là bắt buộc đối với tất cả ứng dụng phân phối qua App Store.

Tệp kê khai phải có mặt trong mọi tệp nhị phân — không chỉ trong ứng dụng chính mà còn trong mọi framework và thư viện tĩnh. Nếu SDK bên thứ ba không cung cấp tệp kê khai, nhà phát triển cần thêm thủ công hoặc liên hệ với nhà cung cấp SDK để được cập nhật.

Tại sao Apple giới thiệu Privacy Manifest

Trước tệp kê khai, nhà phát triển có thể sử dụng rộng rãi API hệ thống (truy cập hệ thống tệp, ngày/giờ, nhật ký hệ thống) mà không có giải thích minh bạch về mục đích sử dụng. Điều này tạo ra nguy cơ rò rỉ dữ liệu qua SDK bên thứ ba có thể thu thập thông tin mà nhà phát triển không biết.

Theo Mysk Inc. (2023), nhiều SDK phổ biến đã sử dụng API để lấy dấu vân tay thiết bị mà không có nhu cầu rõ ràng — ví dụ: đọc thời gian hoạt động để xác định múi giờ hoặc quét thư mục để thu thập siêu dữ liệu. Privacy Manifest buộc phải khai báo mọi hành động như vậy.

Ngoài Required Reason API, tệp kê khai bao gồm phần NSPrivacyTracking — cờ chỉ ra ứng dụng có sử dụng theo dõi hay không (cần ATT), và NSPrivacyCollectedDataTypes — danh sách loại dữ liệu được thu thập theo định dạng Privacy Nutrition Label.

Sự khác biệt giữa Privacy Manifest và Privacy Nutrition Label

Privacy Nutrition Label là bản trình bày hướng đến người dùng trên trang ứng dụng trong App Store, hiển thị dữ liệu mà ứng dụng thu thập. Privacy Manifest là tệp kỹ thuật bên trong tệp nhị phân mà Apple kiểm tra tự động. Nếu dữ liệu trong tệp kê khai không khớp với nhãn trong App Store Connect, Apple từ chối bản dựng.

Do đó, tệp kê khai là nguồn sự thật cho hệ thống xác minh của Apple. Nhãn quyền riêng tư được tạo tự động dựa trên nó, nhưng nhà phát triển phải duy trì cả hai bản trình bày cập nhật. Thay đổi tệp kê khai sau khi xuất bản yêu cầu gửi bản dựng mới để xem xét.

Cấu trúc của PrivacyInfo.xcprivacy

Tệp PrivacyInfo.xcprivacy sử dụng định dạng property list với loại gốc là Dictionary. Các khóa cấp cao nhất chính là: NSPrivacyTracking (Boolean), NSPrivacyTrackingDomains (Array), NSPrivacyCollectedDataTypes (Array), NSPrivacyAccessedAPITypes (Array).

Các khóa cấp cao nhất

Khóa NSPrivacyTracking — giá trị boolean chỉ ra ứng dụng có áp dụng theo dõi hay không (cần ATT). Nếu true, bạn cũng phải chỉ định NSUserTrackingUsageDescription trong Info.plist. Khóa NSPrivacyTrackingDomains — mảng các miền mà theo dõi được áp dụng.

Khóa NSPrivacyCollectedDataTypes — mảng các từ điển, mỗi từ điển mô tả loại dữ liệu được thu thập: danh mục (NSPrivacyCollectedDataType), liên kết (NSPrivacyCollectedDataLinked), mục đích (NSPrivacyCollectedDataTypePurposes). Mục đích bao gồm: quảng cáo bên thứ ba, phân tích, phát triển sản phẩm và cá nhân hóa nội dung.

Khóa NSPrivacyAccessedAPITypes — mảng các từ điển cho mỗi loại Required Reason API: danh mục (NSPrivacyAccessedAPITypeReasons) — lý do cụ thể từ danh sách được Apple phê duyệt, và NSPrivacyAccessedAPIType — định danh loại API.

<!-- PrivacyInfo.xcprivacy -->
<?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>NSPrivacyAccessedAPITypes</key>
    <array>
        <dict>
            <key>NSPrivacyAccessedAPIType</key>
            <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
            <key>NSPrivacyAccessedAPITypeReasons</key>
            <array>
                <string>C617.1</string>
            </array>
        </dict>
    </array>
</dict>
</plist>

Các danh mục dữ liệu trong NSPrivacyCollectedDataTypes

Các loại dữ liệu được chia thành nhiều danh mục: thông tin liên hệ (tên, email, điện thoại), tài chính (dữ liệu thanh toán), định danh (IDFA, ID người dùng), dữ liệu sử dụng (nhật ký, nhấp chuột), chẩn đoán (nhật ký sự cố) và nội dung người dùng (ảnh, video, tệp). Mỗi danh mục được đánh dấu thêm là "liên kết với người dùng" hoặc "không liên kết".

Liên kết có nghĩa là dữ liệu được gắn với tài khoản người dùng; không liên kết có nghĩa là dữ liệu được tổng hợp hoặc ẩn danh. Việc đánh dấu này ảnh hưởng đến cách Apple hiển thị nhãn quyền riêng tư: dữ liệu liên kết được đánh dấu màu vàng, không liên kết — màu xanh lá.

API nào yêu cầu chỉ định lý do

Apple đã xác định một số loại API, mỗi lần sử dụng phải kèm theo lý do cụ thể từ danh sách được phê duyệt. Lý do là mã duy nhất, ví dụ C617.1 hoặc 35F9.1, tương ứng với mục đích cụ thể được Apple cho phép.

Các loại Required Reason API chính

Loại NSPrivacyAccessedAPICategoryFileTimestamp bao gồm API để truy cập dấu thời gian tệp (creationDate, modificationDate). Lý do: C617.1 (đồng bộ tệp), 3B52.1 (sao lưu), 0A2A.1 (chống gian lận).

Loại NSPrivacyAccessedAPICategoryDiskSpace bao gồm API để kiểm tra dung lượng trống trên đĩa (NSFileManager. Kiểm tra (NSFileManager). Lý do: E174.1 (quản lý bộ nhớ đệm), 85F4.1 (tải nội dung), B728.1 (chẩn đoán).

Loại NSPrivacyAccessedAPICategorySystemBootTime bao gồm API truy cập thời gian khởi động hệ thống (uptime). Chỉ có một lý do: 35F9.1 (đo thời gian phiên để phân tích). Bất kỳ sử dụng nào khác đều được coi là fingerprinting.

Danh sách đầy đủ các loại API

• FileTimestamp — truy cập dấu thời gian tệp, được phép cho đồng bộ hóa và sao lưu
• DiskSpace — kiểm tra dung lượng trống, được phép cho quản lý bộ nhớ đệm và tải xuống
• SystemBootTime — thời gian hoạt động, chỉ được phép cho phân tích phiên
• UserDefaults — truy cập UserDefaults của ứng dụng khác, hoàn toàn bị cấm
• ActiveKeyboards — danh sách bàn phím đang hoạt động, được phép cho nhà phát triển IME
• SystemAperture — kích thước phần khuyết trên màn hình, được phép cho ứng dụng ảnh và AR

Mỗi loại có từ 1 đến 5 lý do được phê duyệt. Nhà phát triển phải chọn lý do phù hợp nhất với việc sử dụng API thực tế. Cung cấp lý do không chính xác có thể dẫn đến từ chối bản dựng hoặc khóa tài khoản.

Yêu cầu đối với SDK bên thứ ba

Từ ngày 1 tháng 5 năm 2024, tất cả SDK bên thứ ba — cả nhị phân và mã nguồn mở — phải bao gồm Privacy Manifest trong gói của chúng. Apple kiểm tra tệp kê khai cho tất cả phụ thuộc, và nếu ít nhất một SDK không có tệp kê khai, bản dựng sẽ bị từ chối.

Các SDK lớn (Firebase, Adjust, AppsFlyer, Facebook SDK) đã cập nhật gói của chúng. Nếu dự án của bạn sử dụng SDK ít phổ biến, hãy kiểm tra phiên bản của nó và nếu cần cập nhật hoặc liên hệ với nhà phát triển. Giải pháp tạm thời là thêm tệp kê khai cho SDK thủ công vào dự án, nhưng không được khuyến nghị do sự khác biệt trong quá trình cập nhật.

Cách tạo Privacy Manifest trong Xcode

Bạn có thể tạo PrivacyInfo.xcprivacy thông qua mẫu tích hợp trong Xcode 15+ hoặc thủ công. Hãy xem xét cả hai tùy chọn.

Tạo qua Xcode 15

Xcode 15 bao gồm mẫu Privacy Manifest: File → New → File → Resource → Privacy Manifest. Xcode tạo tệp với cấu trúc cơ bản và điền NSPrivacyTracking và các mảng rỗng cho API và dữ liệu. Sau khi tạo, bạn cần chỉ định thủ công lý do cho mỗi Required Reason API được sử dụng.

Mẫu tự động thêm tệp vào mục tiêu chính. Nếu dự án có nhiều mục tiêu (Extensions, Watch app), bạn cần thêm tệp kê khai vào mỗi mục tiêu. Xcode không kiểm tra sự hiện diện của tệp kê khai trong phụ thuộc tại thời điểm biên dịch — chỉ ở giai đoạn lưu trữ.

// AppDelegate: kiểm tra tệp kê khai ở giai đoạn phát triển
import Foundation

func validatePrivacyManifest() {
    guard let path = Bundle.main.path(
        forResource: "PrivacyInfo", ofType: "xcprivacy"
    ) else {
        print("Không tìm thấy PrivacyInfo.xcprivacy")
        return
    }
    guard let dict = NSDictionary(contentsOfFile: path)
    else { return }
    print("Privacy manifest loaded: \(dict.count) keys")
}

Tạo thủ công qua XML

Bạn có thể tạo PrivacyInfo.xcprivacy thủ công như một tệp XML property list thông thường. Để làm điều này, hãy tạo tệp có tên PrivacyInfo.xcprivacy, viết tiêu đề plist tiêu chuẩn và thêm từ điển gốc với các khóa cần thiết. Đảm bảo rằng tệp đã được thêm vào mục tiêu (Target Membership).

Phương pháp thủ công hữu ích khi bạn cần thêm tệp kê khai vào thư viện tĩnh hoặc phụ thuộc Package Manager mà không sử dụng giao diện Xcode. Sau khi biên dịch, hãy xác minh rằng tệp được bao gồm trong tệp nhị phân bằng lệnh nm hoặc lưu trữ.

Xác thực tệp kê khai trước khi xuất bản

Trước khi gửi bản dựng đến App Store, bạn cần xác minh rằng Privacy Manifest chính xác và đầy đủ. Apple cung cấp một số công cụ xác thực.

Trình xác thực tích hợp của Xcode

Khi lưu trữ dự án (Product → Archive), Xcode thực hiện xác thực tệp kê khai. Nếu tìm thấy lỗi — thiếu tệp kê khai, lý do không chính xác, danh mục trống — việc lưu trữ thất bại với lỗi. Nhật ký lỗi được hiển thị trong Issue navigator, chỉ ra SDK có vấn đề và loại API.

Xác thực bổ sung được thực hiện ở phía App Store Connect khi tải bản dựng lên. Nếu xác thực thất bại, bản dựng bị từ chối với email tự động chứa định danh API có vấn đề và sửa chữa được khuyến nghị.

Xác thực qua dòng lệnh

Để tự động hóa xác thực, hãy sử dụng tập lệnh phân tích tệp nhị phân để tìm kiếm việc sử dụng Required Reason API. Apple cung cấp công cụ libtool và tập lệnh kiểm tra ký hiệu, nhưng cộng đồng đã phát triển các tiện ích thuận tiện hơn.

# Tìm kiếm việc sử dụng API FileTimestamp trong tệp nhị phân
nm MyApp.app/MyApp | grep "NSFileCreationDate"

# Kiểm tra sự hiện diện của PrivacyInfo.xcprivacy trong ứng dụng
find MyApp.app -name "*.xcprivacy"

Các lỗi xác thực phổ biến

Lỗi phổ biến nhất là thiếu tệp kê khai trong một trong các SDK. Ngay cả khi mục tiêu chính chứa tệp kê khai, Apple kiểm tra từng tệp nhị phân riêng lẻ. Lỗi phổ biến thứ hai là mã lý do không chính xác: sử dụng lý do cho một loại API với API từ loại khác.

Lỗi thứ ba là khai báo quá mức các API không thực sự được sử dụng. Nhà phát triển thêm tất cả lý do có thể "để phòng trường hợp", điều này làm các nhà xét duyệt Apple nghi ngờ. Chỉ thêm các danh mục thực sự được sử dụng. Sử dụng trình phân tích tĩnh Xcode để xác minh.