วิธีใช้งาน PrivacyInfo.xcprivacy สำหรับแอปพลิเคชันและ SDK บน iOS

วิธีใช้งาน PrivacyInfo.xcprivacy สำหรับแอปพลิเคชัน iOS? การใช้งาน PrivacyInfo.xcprivacy จำเป็นต้องเพิ่มไฟล์รายการความเป็นส่วนตัว (Privacy Manifest) ที่ถูกต้องลงในเป้าหมายแอปพลิเคชันหรือ SDK ของคุณ, การประกาศรหัสเหตุผลที่ได้รับการอนุมัติสำหรับ API ที่ต้องระบุเหตุผล (Required Reason APIs) ใดๆ ที่ใช้งาน (เช่น User Defaults หรือเวลาบูตระบบ) และการตรวจสอบว่าทรัพยากรบุคคลภายนอก (Third-party Dependencies) เป็นไปตามข้อกำหนดของแมนิเฟสความเป็นส่วนตัวและข้อกำหนดลายเซ็นที่ใช้รูปแบบการแจกจ่ายนั้นๆ

แมนิเฟสความเป็นส่วนตัว (PrivacyInfo.xcprivacy) คือไฟล์รายการคุณสมบัติมาตรฐานที่รวมอยู่ในแอป iOS และ SDK ของบุคคลที่สาม ซึ่งประกาศหมวดหมู่การเก็บรวบรวมข้อมูล การกำหนดค่าโดเมนการติดตาม และเหตุผลที่ได้รับการอนุมัติในการเข้าถึง Required Reason APIs ที่ Apple กำหนด เริ่มตั้งแต่วันที่ 1 พฤษภาคม 2024 เป็นต้นไป แอปที่ส่งไปยัง App Store Connect จะต้องระบุเหตุผลที่ได้รับการอนุมัติสำหรับ Required Reason APIs ที่ใช้โดยโค้ดของแอป รวมถึงโค้ด SDK ของบุคคลที่สามที่เกี่ยวข้องด้วย

ทำความเข้าใจข้อกำหนด Privacy Manifest ของ Apple สำหรับ iOS SDK

สถาปัตยกรรมของ Privacy Manifests: แมนิเฟสแอปพลิเคชันหลักเทียบกับแมนิเฟส SDK ที่ฝังอยู่

กรอบงานแมนิเฟสความเป็นส่วนตัวของ Apple กำหนดรูปแบบความโปร่งใสแบบโมดูลาร์ทั่วทั้งห่วงโซ่อุปทานซอฟต์แวร์ iOS แทนที่จะกำหนดให้แอปพลิเคชันโฮสต์ต้องตรวจสอบและประกาศรายละเอียดการใช้งานภายในของไลบรารีที่นำเข้าทุกตัวด้วยตนเอง Apple ได้แบ่งการกำกับดูแลความเป็นส่วนตัวออกเป็นชั้นๆ ดังนี้:

• Main Application Manifest: ครอบคลุมการรวบรวมข้อมูลระดับแรก (First-party), โดเมนการติดตามระดับแอป และ Required Reason APIs ที่เรียกใช้โดยตรงจากโค้ดเป้าหมายแอปพลิเคชันหลัก
• Embedded SDK Manifests: การประกาศ Required Reason API จะต้องเป็นเจ้าของโดยแอปหรือโค้ด SDK ของบุคคลที่สามที่ใช้ API เหล่านั้น สำหรับไฟล์ปฏิบัติการและไลบรารีแบบไดนามิก ชุดรวม (Bundle) ที่มีไฟล์ปฏิบัติการหรือไลบรารีนั้นจะต้องรวมแมนิเฟสความเป็นส่วนตัวที่เกี่ยวข้องด้วย โดย SDK ของบุคคลที่สามไม่สามารถพึ่งพาแมนิเฟสของแอปโฮสต์เพื่อรายงานการใช้งาน Required Reason API ของ SDK นั้นได้
• Automated Dependency Aggregation: เมื่อมีการเก็บถาวรแอปพลิเคชันใน Xcode 15 ขึ้นไป ระบบการสร้าง (Build System) จะสำรวจกราฟการพdependency ค้นหาไฟล์ PrivacyInfo.xcprivacy ทั้งหมดที่รวมอยู่ และรวบรวมเป็นรายงานความเป็นส่วนตัวชุดเดียวที่เป็นอันหนึ่งอันเดียวกัน

คีย์การกำหนดค่ารูทหลักสี่รายการ

ไฟล์ PrivacyInfo.xcprivacy ทุกไฟล์มีโครงสร้างเป็นพจนานุกรมรายการคุณสมบัติ XML ที่มีคีย์ระดับรูทสูงสุดสี่รายการ:

• NSPrivacyTracking (Boolean): ประกาศว่าแอปพลิเคชันหรือ SDK ใช้ข้อมูลที่รวบรวมจากแอปเพื่อการติดตามภายใต้คำจำกัดความของ Apple App Tracking Transparency (ATT) หรือไม่
• NSPrivacyTrackingDomains (Array of Strings): แสดงรายการโดเมนอินเทอร์เน็ตที่เชื่อมต่อโดยแอปหรือ SDK ที่มีส่วนร่วมในการติดตาม หากผู้ใช้ไม่อนุญาตการให้สิทธิ์ ATT ระบบ iOS จะบล็อกการเชื่อมต่อเครือข่ายไปยังโดเมนที่ประกาศไว้ในอาร์เรย์นี้ หากแอปหรือ SDK ไม่ได้เชื่อมต่อกับโดเมนการติดตาม สามารถละเว้นคีย์นี้ได้
• NSPrivacyCollectedDataTypes (Array of Dictionaries): รายงานหมวดหมู่ข้อมูลที่ Apple กำหนดซึ่งแอปหรือ SDK รวบรวมเกี่ยวกับบุคคลที่ใช้แอป พร้อมทั้งระบุว่าข้อมูลนั้นเชื่อมโยงกับตัวตนของผู้ใช้หรือไม่ ใช้สำหรับการติดตามหรือไม่ และวัตถุประสงค์ในการดำเนินงานที่รวบรวมข้อมูลนั้น
• NSPrivacyAccessedAPITypes (Array of Dictionaries): ประกาศ Required Reason APIs ที่ Apple กำหนดซึ่งถูกเรียกใช้โดยไบนารี พร้อมด้วยรหัสเหตุผลสตริงที่ได้รับการอนุมัติ

การบังคับใช้การนำเข้า App Store Connect และการวินิจฉัยข้อผิดพลาด

App Store Connect จะบังคับใช้แมนิเฟสความเป็นส่วนตัวในระหว่างการนำเข้าไบนารี:

• Missing API Declaration (ITMS-91053): เกิดขึ้นเมื่อไบนารีที่คอมไพล์แล้วหรือไลบรารีที่ลิงก์เรียกใช้สัญลักษณ์ Required Reason API แต่คีย์หมวดหมู่ที่เกี่ยวข้องหายไปจาก NSPrivacyAccessedAPITypes
• Invalid Reason Code Declaration: เกิดขึ้นเมื่อแมนิเฟสประกาศสตริงเหตุผลที่ไม่ได้รับอนุมัติ จัดรูปแบบไม่ถูกต้อง หรือเลิกใช้งานแล้วสำหรับหมวดหมู่ API เฉพาะ
• Required Third-Party SDK Manifest Missing: บังคับใช้ในสถานการณ์การส่งผลงานที่กำหนดโดยข้อกำหนด SDK ของบุคคลที่สามปัจจุบันของ Apple สำหรับ SDK ที่แสดงรายการ ซึ่งต้องมีทั้งแมนิเฟสความเป็นส่วนตัวและลายเซ็นดิจิทัลที่ถูกต้องสำหรับการแจกจ่ายไบนารี

นักพัฒนาที่ทำการรวมระบบการระบุแหล่งที่มาของลูกค้า (Client Attribution) และการทำ Deep Linking สามารถศึกษาเอกสาร การรวมระบบ iOS SDK สำหรับข้อกำหนดทางเทคนิคเกี่ยวกับการประกาศแมนิเฟส

ดูเพิ่มเติม: iOS SDK ──> สถาปัตยกรรม Mobile Attribution

หมวดหมู่ Required Reason API และรหัสเหตุผลที่ได้รับการอนุมัติ

หมวดหมู่ Required Reason API ทั้งห้า

อ้างอิงจาก Apple Developer Technote TN3183, Apple กำหนดหมวดหมู่ API เฉพาะ 5 หมวดหมู่ที่ต้องใช้รหัสเหตุผลที่ชัดเจนใน NSPrivacyAccessedAPITypes โดย Mobile SDK และแอปพลิเคชัน iOS มักจะโต้ตอบกับ 4 หมวดหมู่หลัก:

• NSPrivacyAccessedAPICategoryUserDefaults: การเข้าถึงการตั้งค่าแอปในเครื่องผ่าน UserDefaults หรือ NSUserDefaults
• NSPrivacyAccessedAPICategorySystemBootTime: การวัดเวลาที่ผ่านไปหรือประทับเวลาโดยใช้ API การบูตระบบ เช่น sysctl(KERN_BOOTTIME) หรือ systemUptime
• NSPrivacyAccessedAPICategoryDiskSpace: การตรวจสอบความจุของระบบไฟล์ผ่าน statfs, statvfs หรือ volumeAvailableCapacityKey
• NSPrivacyAccessedAPICategoryFileTimestamp: การตรวจสอบวันที่สร้างหรือแก้ไขไฟล์ผ่าน stat, getattrlist หรือ contentModificationDateKey
• NSPrivacyAccessedAPICategoryActiveKeyboards: การตรวจสอบส่วนขยายคีย์บอร์ดกำหนดเองที่ใช้งานอยู่ (ส่วนใหญ่ใช้โดยยูทิลิตี้คีย์บอร์ดเฉพาะทาง)

การแมปrรหัสเหตุผลที่ได้รับการอนุมัติที่เลือกสำหรับกรณีการใช้งาน SDK ทั่วไป

ตารางด้านล่างเน้นไปที่หมวดหมู่ที่พบได้บ่อยใน Mobile SDK อเนกประสงค์ โปรดดูเอกสารปัจจุบันของ Apple สำหรับรายการเหตุผลที่สมบูรณ์ ซึ่งรวมถึง Active Keyboards ด้วย เพื่อให้เป็นไปตามแนวทางของ Apple นักพัฒนาต้องเลือกrรหัสเหตุผลที่ตรงกับการใช้งานข้อมูลรันタイムจริงของตนอย่างเคร่งครัด:

การสร้างรายการคุณสมบัติ PrivacyInfo.xcprivacy ตัวอย่าง

การกำหนดค่าประเภทการรวบรวมข้อมูล

อาร์เรย์ NSPrivacyCollectedDataTypes จะรายงานหมวดหมู่ข้อมูลที่ Apple กำหนดซึ่งแอปหรือ SDK รวบรวมเกี่ยวกับผู้ใช้แอป พร้อมทั้งระบุว่าข้อมูลนั้นเชื่อมโยงกับตัวตนของผู้ใช้หรือไม่ ใช้สำหรับการติดตามหรือไม่ และวัตถุประสงค์ในการดำเนินงานสำหรับการรวบรวมข้อมูลนั้น:

• NSPrivacyCollectedDataType: ตัวระบุสตริงมาตรฐานของ Apple (เช่น NSPrivacyCollectedDataTypeDeviceID)
• NSPrivacyCollectedDataTypeLinked: บูลีนที่ระบุว่าข้อมูลนั้นเชื่อมโยงกับตัวตนของผู้ใช้แต่ละคนหรือไม่
• NSPrivacyCollectedDataTypeTracking: บูลีนที่ระบุว่าข้อมูลนั้นใช้สำหรับการติดตามข้ามแอปหรือไม่
• NSPrivacyCollectedDataTypePurposes: อาร์เรย์ของสตริงวัตถุประสงค์มาตรฐาน (เช่น NSPrivacyCollectedDataTypePurposeAnalytics)

การประกาศโดเมนการติดตาม

หาก SDK หรือแอปพลิเคชันมีส่วนร่วมในการติดตามภายใต้คำจำกัดความของ ATT จะต้องประกาศโดเมนการติดตามที่เกี่ยวข้องทั้งหมดภายใต้ NSPrivacyTrackingDomains หากผู้ใช้อุปกรณ์ไม่อนุญาตให้มีการติดตาม ระบบ iOS จะบล็อกการเชื่อมต่อเครือข่ายไปยังโดเมนที่ประกาศไว้ หากแอปหรือ 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>

การแก้ไขข้อผิดพลาดการลงนามรหัส Resource Bundle ของ CocoaPods

สาเหตุหลัก: ความล้มเหลวในการลงนาม Resource Bundle ใน Xcode 15 และ 16

เมื่อรวม Dependency ผ่าน CocoaPods ใน Xcode 15 หรือ 16 นักมักจะพบกับการหยุดชะงักของการคอมไพล์บ่อยครั้ง:

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

ความล้มเหลวในการสร้างนี้คือปัญหาการรวมกันระหว่าง Xcode และ CocoaPods:

• ไลบรารีแบบสถิต .a แบบดั้งเดิมไม่สามารถมีทรัพยากร เช่น PrivacyInfo.xcprivacy ได้โดยตรง Apple จึงแนะนำให้แพ็กเกจโค้ดและทรัพยากร SDK แบบสถิตมารวมกันไว้ภายในเฟรม워크แบบสถิต
• การรวม CocoaPods บางรูปแบบจะสร้างเป้าหมาย Resource-bundle แยกต่างหากเพื่อแจกจ่ายทรัพยากรควบคู่ไปกับไลบรารีแบบสถิต
• เป้าหมาย Resource-bundle ที่สร้างโดย CocoaPods บางตัวอาจสืบทอดการกำหนดค่าการลงนามที่ทำให้การสร้าง Xcode หยุดลงและร้องขอทีมพัฒนา นี่คือปัญหาการรวมระบบการสร้างมากกว่าข้อกำหนดสีมาร์ PrivacyInfo.xcprivacy

การใช้วิธีแก้ปัญหาเฉพาะจุดในระดับ Build-System ใน Podfile

เพื่อแก้ไขข้อผิดพลาดนี้ในการสร้างแบบอัตโนมัติ นักพัฒนาสามารถใช้ฮุก post_install แบบขอบเขตเฉพาะใน Podfile ของโปรเจกต์ เนื่องจากนี่คือวิธีแก้ปัญหาการสร้างระบบสำหรับ Resource bundles ที่ไม่มีไฟล์ปฏิบัติการ ทีมงานจึงควรจำกัดขอบเขตไว้ที่เป้าหมายชุดรวมที่ได้รับผลกระทบเฉพาะเจาะจง หรือตรวจสอบความถูกต้องของ Dependency ที่ได้รับผลกระทบก่อนนำไปใช้ทั่วทั้งโปรเจกต์

สคริปต์ 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

เพื่อตรวจสอบว่าเป้าหมาย First-party และ Dependency ของ Third-party ทั้งหมดได้รับการประกาศอย่างถูกต้องก่อนส่งไบนารี:

1. เปิดโปรเจกต์ของคุณใน Xcode 15 หรือ newer
2. เลือก Product > Archive เพื่อสร้าง Release Archive
3. ใน Xcode Organizer ให้คลิกขวา (หรือ Control-click) ที่ Archive แล้วเลือก Generate Privacy Report
4. บันทึกและตรวจสอบรายงาน PDF ที่สร้างขึ้นเพื่อยืนยันว่า Required Reason APIs, หมวดหมู่ข้อมูล และแมนิเฟส SDK ของบุคคลที่สามทั้งหมดปรากฏอย่างถูกต้อง

การวิเคราะห์สถิตผ่านบรรทัดคำสั่ง (Command-Line): การสแกน Heuristic ก่อนส่ง

ทีมพัฒนาสามารถใช้การตรวจสอบฮิวริสติกก่อนส่งภายในไปรพลายน์ CI/CD (Continuous Integration/Continuous Deployment) โดยสแกนไบนารีที่คอมไพล์แล้วเพื่อหาจำกัดสัญลักษณ์โดยใช้ nm และ otool:

# สแกนไบนารีแอปพลิเคชันที่คลายแพ็กแล้วเพื่อหาตัวเลือกสัญลักษณ์ Required Reason 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"

การมีอยู่ของสัญลักษณ์ไม่ได้หมายความว่าเหตุผลที่ได้รับการอนุมัติใดใช้ได้ผล โปรดตรวจสอบเส้นทางการเรียกใช้งานและกรณีการใช้งานจริงก่อนแก้ไขแมนิเฟส ทีมงานต้องใช้ฟังก์ชัน Generate Privacy Report ของ Xcode และการตรวจสอบล่วงหน้าของ App Store Connect เพื่อการตรวจสอบที่เชื่อถือได้

เมทริกซ์การวินิจฉัย: สาเหตุหลักของการปฏิเสธแมนิเฟสความเป็นส่วนตัวใน App Store

สรุปและกรอบการตัดสินใจ

กรอบงานแมนิเฟสความเป็นส่วนตัวของ Apple บังคับใช้ความโปร่งใสทั่วทั้งห่วงโซ่อุปทานซอฟต์แวร์ iOS การรับรองว่าการส่งแอปไปยัง App Store จะดำเนินไปอย่างราบรื่น กำหนดให้ทีมพัฒนาต้องตรวจสอบโค้ด First-party สำหรับการใช้งาน Required Reason API, ตรวจสอบว่า Dependency ของ SDK บุคคลที่สามเป็นไปตามข้อกำหนดแมนิเฟสความเป็นส่วนตัวที่ใช้กับการใช้งาน API ของตน และจัดการการลงนามชุดทรัพยากร CocoaPods อย่างเหมาะสม

สำหรับการประกาศแมนิเฟสความเป็นส่วนตัวเฉพาะผลิตภัณฑ์ โปรดตรวจสอบ เอกสารประกอบของ OpoInstall และเปรียบเทียบแมนิเฟสที่จัดส่งกับการบูรณาการจริงของแอปพลิเคชันรวมถึงข้อกำหนดปัจจุบันของ Apple

วัสดุและแหล่งข้อมูลที่เกี่ยวข้อง

• แนวคิด: Privacy Manifests, Required Reason APIs, Resource Bundle Code Signing, Privacy Reports, App Store Compliance

• เทคโนโลยี: Xcode 15+, ตัวจัดการ Dependency CocoaPods, Swift Package Manager, OpoInstall iOS SDK

• มาตรฐาน: Apple Privacy Manifest Specification, App Store Review Guidelines Section 5.1.1

• API และการกำหนดค่า: PrivacyInfo.xcprivacy, NSPrivacyAccessedAPITypes, Podfile post_install Hook

เอกสารประกอบอย่างเป็นทางการ

• เอกสารสำหรับนักพัฒนาของ Apple เกี่ยวกับการอธิบายการใช้งาน Required Reason API

• เอกสารสำหรับนักพัฒนาของ Apple เกี่ยวกับไฟล์ Privacy Manifest

• เอกสารสำหรับนักพัฒนาของ Apple เกี่ยวกับข้อกำหนด SDK ของบุคคลที่สามที่กำลังจะมาถึง

• แนวทางปฏิบัติในการตรวจสอบ App Store ของ Apple ส่วนที่ 5.1.1