如何為 iOS App 與 SDK 實作 PrivacyInfo.xcprivacy

如何為 iOS App 實作 PrivacyInfo.xcprivacy？實作 PrivacyInfo.xcprivacy 需要將有效的隱私權資訊清單（Privacy Manifest）加入您的應用程式或 SDK 目標（Target）、針對所使用的任何規定原因 API（例如 User Defaults 或系統開機時間）宣告核准的原因代碼，並驗證第三方相依性是否符合其散布形式所適用的隱私權資訊清單與簽署要求。

隱私權資訊清單（PrivacyInfo.xcprivacy）是打包在 iOS App 與第三方 SDK 內部的標準化屬性列表檔案，用於宣告資料收集類別、追蹤網域設定，以及存取 Apple 指定之規定原因 API 的核准正當理由。自 2024 年 5 月 1 日起，提交至 App Store Connect 的 App 必須包含 App 程式碼（包含適用的第三方 SDK 程式碼）所使用之規定原因 API 的核准原因。

了解 iOS SDK 的 Apple 隱私權資訊清單要求

隱私權資訊清單的架構：主應用程式資訊清單與內嵌 SDK 資訊清單

Apple 的隱私權資訊清單框架在 iOS 軟體供應鏈中建立了模組化的透明度模型。Apple 並未要求主應用程式手動稽核並宣告每個匯入程式庫的內部實作細節，而是將隱私權治理劃分為不同的層級：

• 主應用程式資訊清單 (Main Application Manifest)：涵蓋第一方資料收集、App 層級追蹤網域，以及由主要應用程式目標程式碼直接呼叫的規定原因 API。
• 內嵌 SDK 資訊清單 (Embedded SDK Manifests)：規定原因 API 宣告必須由使用該 API 的 App 或第三方 SDK 程式碼擁有。對於執行檔與動態程式庫而言，包含該執行檔或程式庫的套件必須包含相關的隱私權資訊清單；第三方 SDK 無法依賴主 App 的資訊清單來回報 SDK 對規定原因 API 的使用情況。
• 自動化相依性彙整 (Automated Dependency Aggregation)：當 App 在 Xcode 15 或更新版本中進行封存（Archive）時，建置系統會走訪相依性圖表，尋找所有打包的 PrivacyInfo.xcprivacy 檔案，並將其彙整成單一、統一的隱私權報告。

四個根設定金鑰

每個 PrivacyInfo.xcprivacy 檔案都結構化為一個 XML 屬性列表字典，包含最多四個根層級金鑰：

• NSPrivacyTracking (布林值)：宣告 App 或 SDK 是否根據 Apple App 追蹤透明度 (ATT) 定義，使用從 App 收集的資料進行追蹤。
• NSPrivacyTrackingDomains (字串陣列)：列出 App 或 SDK 連線且會進行追蹤的網際網路網域。如果使用者未授權 ATT，iOS 會封鎖對此陣列中所宣告網域的網路連線。如果 App 或 SDK 未連線至追蹤網域，則可省略此金鑰。
• NSPrivacyCollectedDataTypes (字典陣列)：回報 Apple 定義的 App 或 SDK 收集關於使用該 App 之人員的資料類別，以及該資料是否與使用者身分連結、是否用於追蹤，以及收集的操作目的。
• NSPrivacyAccessedAPITypes (字典陣列)：宣告二進位檔所呼叫的 Apple 指定規定原因 API，並附上核准的字串原因代碼。

App Store Connect 提交強制執行與錯誤診斷

App Store Connect 會在二進位檔上傳期間強制執行隱私權資訊清單：

• 缺少 API 宣告 (ITMS-91053)：當已編譯的二進位檔或連結的程式庫呼叫了規定原因 API 符號，但 NSPrivacyAccessedAPITypes 中缺少對應的類別金鑰時觸發。
• 無效的原因代碼宣告：當資訊清單針對特定 API 類別宣告了未核准、格式錯誤或已棄用的原因字串時發生。
• 缺少規定的第三方 SDK 資訊清單：依據 Apple 現行針對列出之 SDK 的第三方 SDK 要求中所定義的提交情境強制執行，二進位檔散布需要隱私權資訊清單與有效的數位簽章。

整合客戶端歸因與深度連結的開發人員可參閱 iOS SDK 整合說明文件，以取得關於資訊清單宣告的技術規格。

參閱：iOS SDK ──> 行動歸因架構

規定原因 API 類別與核准的原因代碼

五個規定原因 API 類別

根據 Apple Developer 技術備忘錄 TN3183，Apple 定義了五個需要在 NSPrivacyAccessedAPITypes 中提供明確正當理由代碼的特定 API 類別。行動 SDK 與 iOS 應用程式通常會互動四個主要類別：

• NSPrivacyAccessedAPICategoryUserDefaults：透過 UserDefaults 或 NSUserDefaults 存取本機 App 設定。
• NSPrivacyAccessedAPICategorySystemBootTime：使用系統開機 API（如 sysctl(KERN_BOOTTIME) 或 systemUptime）測量經過的時間或時間戳記。
• NSPrivacyAccessedAPICategoryDiskSpace：透過 statfs、statvfs 或 volumeAvailableCapacityKey 檢查檔案系統容量。
• NSPrivacyAccessedAPICategoryFileTimestamp：透過 stat、getattrlist 或 contentModificationDateKey 檢查檔案建立或修改日期。
• NSPrivacyAccessedAPICategoryActiveKeyboards：檢查作用中的自訂鍵盤擴充功能（主要由專門的鍵盤公用程式使用）。

常見 SDK 使用情境的精選核准原因代碼對應

下表著重於通用的行動 SDK 中常見的類別；如需完整的 razão 列表（包含作用中鍵盤），請參閱 Apple 的最新說明文件。為遵守 Apple 規範，開發人員必須選擇與其實際執行階段資料使用情況嚴格相符的原因代碼：

建構範例 PrivacyInfo.xcprivacy 屬性列表

設定資料收集類型

NSPrivacyCollectedDataTypes 陣列回報 Apple 定義的 App 或 SDK 收集關於使用該 App 之人員的資料類別，以及該資料是否與使用者身分連結、是否用於追蹤，以及收集的操作目的：

• NSPrivacyCollectedDataType：標準的 Apple 字串識別碼（例如 NSPrivacyCollectedDataTypeDeviceID）。
• NSPrivacyCollectedDataTypeLinked：布林值，表示資料是否與個別使用者的身分連結。
• NSPrivacyCollectedDataTypeTracking：布林值，表示資料是否用於跨 App 追蹤。
• NSPrivacyCollectedDataTypePurposes：標準目的字串的陣列（例如 NSPrivacyCollectedDataTypePurposeAnalytics）。

宣告追蹤網域

如果 SDK 或應用程式根據 ATT 定義進行追蹤，所有對應的追蹤網域都必須在 NSPrivacyTrackingDomains 下宣告。如果使用者未授權追蹤，iOS 會封鎖對所宣告網域的網路連線。如果 App 或 SDK 未進行追蹤，應將 NSPrivacyTracking 設為 false，並可省略 NSPrivacyTrackingDomains。

以下的屬性列表設定展示了範例 PrivacyInfo.xcprivacy 結構。請僅包含反映您應用程式實際實作的類別與原因：

```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>

解決 CocoaPods 資源套件程式碼簽署錯誤

根本原因：Xcode 15 與 16 中的資源套件簽署失敗

當在 Xcode 15 或 16 中透過 CocoaPods 整合相依性時，開發人員經常會遇到編譯中斷的情況：

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

此建置失敗是一個 Xcode 與 CocoaPods 整合問題：

• 傳統的 .a 靜態程式庫無法直接包含資源，例如 PrivacyInfo.xcprivacy。Apple 建議將靜態 SDK 程式碼與資源一起打包在靜態框架 (Static Framework) 內。
• 某些 CocoaPods 整合改為產生獨立的資源套件目標，以將資源與靜態程式庫一同散布。
• 特定由 CocoaPods 產生的資源套件目標可能會繼承簽署設定，導致 Xcode 建置時中斷並要求提供開發團隊。這是建置系統整合問題，而非 PrivacyInfo.xcprivacy 結構描述要求。

在 Podfile 中套用針對性的建置系統因應措施

為了在自動化建置中解決此錯誤，開發人員可以在專案的 Podfile 中使用具有範圍限制的 post_install 鉤子 (Hook)。由於這是針對非執行檔資源套件的建置系統因應措施，團隊應將其範圍限定在特定受影響的套件目標，或在全域套用變更前驗證受影響的相依性。

以下 Ruby 指令碼示範如何迭代 CocoaPods 目標並停用指定資源套件目標上的簽署：

post_install do |installer|
  # 指定遇到沒有開發團隊簽署錯誤的非執行檔資源套件目標
  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|
        # 從指定的非執行檔資源套件中移除程式碼簽署要求
        config.build_settings['CODE_SIGNING_ALLOWED'] = 'NO'
        config.build_settings['CODE_SIGN_IDENTITY'] = ''
      end
    end
  end
end

在 Xcode 中稽核與產生彙整的隱私權報告

透過 Xcode 封存管理器產生統一的隱私權報告

若要驗證所有第一方目標與第三方相依性在提交二進位檔前是否都已正確宣告：

1. 在 Xcode 15 或更新版本中開啟您的專案。
2. 選取 Product > Archive 以建立發布封存。
3. 在 Xcode 組織器 (Organizer) 中，對封存按一下滑鼠右鍵（或按住 Control 鍵點擊）並選取 Generate Privacy Report。
4. 儲存並檢查產生的 PDF 報告，以確認所有規定原因 API、資料類別與第三方 SDK 資訊清單皆正確顯示。

命令列靜態分析：提交前啟發式掃描

開發團隊可以在持續整合 (CI/CD) 管線內實作啟發式提交前稽核，藉由使用 nm 與 otool 掃描已編譯二進位檔中的受限制符號：

# 掃描未封裝的應用程式二進位檔以尋找候選的規定原因 API 符號
nm -u /path/to/Payload/YourApp.app/YourApp | grep -E 'sysctl|statfs|statvfs|getattrlist|NSUserDefaults'

# 檢查內嵌框架與套件中是否有 PrivacyInfo.xcprivacy 資訊清單
find /path/to/Payload/YourApp.app -name "PrivacyInfo.xcprivacy"

符號的存在本身並不能確立適用哪種核准原因；在修改資訊清單之前，請先檢閱實際的呼叫路徑與使用情境。團隊必須使用 Xcode 的 Generate Privacy Report 與 App Store Connect 預先檢查來進行權威驗證。

診斷矩陣：App Store 隱私權資訊清單遭拒的根本原因

摘要與決策架構

Apple 的隱私權資訊清單框架強制執行 iOS 軟體供應鏈的透明度。確保能順利提交 App Store 需要開發團隊稽核第一方程式碼的規定原因 API 使用情況、驗證第三方 SDK 相依性是否符合其 API 使用適用的隱私權資訊清單要求，以及妥善管理 CocoaPods 資源套件程式碼簽署。

如需特定產品的隱私權資訊清單宣告，請參閱 OpoInstall 說明文件，並將出廠的資訊清單與應用程式的實際整合及 Apple 的最新要求進行比較。

相關資料

• 概念：隱私權資訊清單、規定原因 API、資源套件程式碼簽署、隱私權報告、App Store 合規性

• 技術：Xcode 15+、CocoaPods 相依性管理工具、Swift Package Manager、OpoInstall iOS SDK

• 標準：Apple 隱私權資訊清單規格、App Store 審查指南第 5.1.1 節

• API 與設定：PrivacyInfo.xcprivacy、NSPrivacyAccessedAPITypes、Podfile post_install 鉤子

官方說明文件

• Apple 開發人員說明文件：描述規定原因 API 的使用

• Apple 開發人員說明文件：隱私權資訊清單檔案

• Apple 開發人員說明文件：即將推出的第三方 SDK 要求

• Apple App Store 審查指南第 5.1.1 節