Privacy Manifest — ما هو، ملف PrivacyInfo.xcprivacy والمتطلبات

ما هو Privacy Manifest؟

Privacy Manifest هو ملف PrivacyInfo.xcprivacy بتنسيق property list (XML) يعلن عن أنواع البيانات التي يجمعها التطبيق ولماذا يستخدم API معينة. قدمت Apple البيانات كجزء من مبادرة لزيادة شفافية الخصوصية، مماثلة لـ Privacy Nutrition Label، ولكن على مستوى الكود والملف الثنائي.

الغرض الرئيسي من البيان هو توثيق استخدام ما يسمى Required Reason API. هذه هي فئات API التي يمكن استخدامها لأخذ البصمة الرقمية للجهاز (fingerprinting)، لذلك يجب أن يكون كل استخدام مصحوبًا بإعلان سبب محدد من القائمة المعتمدة من Apple.

اعتبارًا من 1 مايو 2024، ترفض Apple البنيات التي لا تحتوي على Privacy Manifest. ينطبق هذا على كل من الأهداف الرئيسية للتطبيق وجميع SDK والتبعيات المضمنة. وفقًا WWDC 2023، البيان إلزامي لجميع التطبيقات الموزعة عبر App Store.

يجب أن يكون البيان موجودًا في كل ملف ثنائي — ليس فقط في التطبيق الرئيسي ولكن أيضًا في كل إطار ومكتبة ثابتة. إذا لم يوفر SDK تابع لجهة خارجية بيانًا، فيجب على المطور إضافته يدويًا أو الاتصال بمزود SDK للحصول على تحديث.

لماذا قدمت Apple Privacy Manifest

قبل البيانات، كان بإمكان المطورين استخدام API نظام واسعة (الوصول إلى نظام الملفات، التاريخ/الوقت، سجلات النظام) بدون شرح شفاف لغرض الاستخدام. خلق هذا خطر تسرب البيانات عبر SDK التابعة لجهات خارجية التي يمكنها جمع المعلومات دون علم المطور.

وفقًا Mysk Inc. (2023)، استخدمت العديد من SDK الشهيرة API لأخذ بصمة الجهاز دون ضرورة واضحة — على سبيل المثال، قراءة وقت التشغيل لتحديد المنطقة الزمنية أو مسح الدلائل لجمع البيانات الوصفية. يلزم Privacy Manifest بالإعلان عن كل إجراء من هذا القبيل.

بالإضافة إلى Required Reason API، يتضمن البيان قسم NSPrivacyTracking — علامة تشير إلى ما إذا كان التطبيق يستخدم التتبع (يتطلب ATT)، و NSPrivacyCollectedDataTypes — قائمة بأنواع البيانات التي تم جمعها بتنسيق Privacy Nutrition Label.

الفرق بين Privacy Manifest و Privacy Nutrition Label

Privacy Nutrition Label هو تمثيل للمستخدم على صفحة التطبيق في App Store، يظهر البيانات التي يجمعها التطبيق. Privacy Manifest هو ملف تقني داخل الملف الثنائي تتحقق منه Apple تلقائيًا. إذا كانت البيانات في البيان لا تتطابق مع التصنيفات في App Store Connect، ترفض Apple البناء.

وبالتالي، البيان هو مصدر الحقيقة لنظام التحقق من Apple. يتم إنشاء تصنيفات الخصوصية تلقائيًا بناءً عليه، ولكن يجب على المطور الحفاظ على كلا التمثيلين محدثين. يتطلب تغيير البيان بعد النشر إرسال بناء جديد للمراجعة.

هيكل PrivacyInfo.xcprivacy

يستخدم ملف PrivacyInfo.xcprivacy تنسيق property list مع نوع جذر Dictionary. المفاتيح الرئيسية على المستوى الأعلى هي: NSPrivacyTracking (Boolean)، NSPrivacyTrackingDomains (Array)، NSPrivacyCollectedDataTypes (Array)، NSPrivacyAccessedAPITypes (Array).

المفاتيح على المستوى الأعلى

المفتاح NSPrivacyTracking — قيمة منطقية تشير إلى ما إذا كان التطبيق يطبق التتبع (يتطلب ATT). إذا كان true، يجب أيضًا تحديد NSUserTrackingUsageDescription في Info.plist. المفتاح NSPrivacyTrackingDomains — مصفوفة من النطاقات التي يتم تطبيق التتبع عليها.

المفتاح NSPrivacyCollectedDataTypes — مصفوفة من القواميس، يصف كل منها نوع البيانات التي تم جمعها: الفئة (NSPrivacyCollectedDataType)، الربط (NSPrivacyCollectedDataLinked)، الغرض (NSPrivacyCollectedDataTypePurposes). تشمل الأغراض: إعلانات الأطراف الثالثة، التحليلات، تطوير المنتج، وتخصيص المحتوى.

المفتاح NSPrivacyAccessedAPITypes — مصفوفة من القواميس لكل فئة من Required Reason API: الفئة (NSPrivacyAccessedAPITypeReasons) — سبب محدد من القائمة المعتمدة من Apple، و NSPrivacyAccessedAPIType — معرف فئة 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>

فئات البيانات في NSPrivacyCollectedDataTypes

تنقسم أنواع البيانات إلى عدة فئات: معلومات الاتصال (الاسم، البريد الإلكتروني، الهاتف)، الأمور المالية (بيانات الدفع)، المعرفات (IDFA، معرف المستخدم)، بيانات الاستخدام (السجلات، النقرات)، التشخيص (سجلات الأعطال) و محتوى المستخدم (الصور، الفيديو، الملفات). يتم تصنيف كل فئة إضافية على أنها «مرتبطة بالمستخدم» أو «غير مرتبطة».

مرتبطة تعني أن البيانات مرتبطة بحساب المستخدم؛ غير مرتبطة تعني أن البيانات مجمعة أو مجهولة المصدر. يؤثر هذا التصنيف على كيفية عرض Apple لتصنيف الخصوصية: البيانات المرتبطة ملونة باللون الأصفر، غير المرتبطة باللون الأخضر.

ما API التي تتطلب تحديد الأسباب

حددت Apple عدة فئات من API، كل استخدام لها يجب أن يكون مصحوبًا بسبب محدد من القائمة المعتمدة. السبب هو رمز فريد، على سبيل المثال C617.1 أو 35F9.1، مرتبط بغرض محدد تسمح به Apple.

الفئات الرئيسية لـ Required Reason API

تتضمن فئة NSPrivacyAccessedAPICategoryFileTimestamp API للوصول إلى الطوابع الزمنية للملفات (creationDate, modificationDate). الأسباب: C617.1 (مزامنة الملفات)، 3B52.1 (النسخ الاحتياطي)، 0A2A.1 (مكافحة الاحتيال).

تتضمن فئة NSPrivacyAccessedAPICategoryDiskSpace API للتحقق من المساحة الحرة على القرص (NSFileManager. التحقق (NSFileManager). الأسباب: E174.1 (إدارة ذاكرة التخزين المؤقت)، 85F4.1 (تنزيل المحتوى)، B728.1 (التشخيص).

تتضمن فئة NSPrivacyAccessedAPICategorySystemBootTime API للوصول إلى وقت تشغيل النظام (uptime). سبب واحد فقط: 35F9.1 (قياس وقت الجلسة للتحليلات). أي استخدام آخر يعتبر بصمة رقمية.

القائمة الكاملة لفئات API

• FileTimestamp — الوصول إلى الطوابع الزمنية للملفات، مسموح به للمزامنة والنسخ الاحتياطي
• DiskSpace — التحقق من المساحة الحرة، مسموح به لإدارة ذاكرة التخزين المؤقت والتنزيلات
• SystemBootTime — وقت التشغيل، مسموح به فقط لتحليلات الجلسات
• UserDefaults — الوصول إلى UserDefaults للتطبيقات الأخرى، ممنوع تمامًا
• ActiveKeyboards — قائمة لوحات المفاتيح النشطة، مسموح به لمطوري IME
• SystemAperture — حجم القطع على الشاشة، مسموح به لتطبيقات الصور والواقع المعزز

كل فئة لها من 1 إلى 5 أسباب معتمدة. يجب على المطور اختيار السبب الأكثر تطابقًا مع الاستخدام الفعلي لـ API. تقديم سبب غير دقيق قد يؤدي إلى رفض البناء أو حظر الحساب.

متطلبات SDK التابعة لجهات خارجية

اعتبارًا من 1 مايو 2024، جميع SDK التابعة لجهات خارجية — ثنائية ومفتوحة المصدر — ملزمة بتضمين Privacy Manifest في حزمتها. تتحقق Apple من البيانات لجميع التبعيات، وإذا كان SDK واحد على الأقل لا يحتوي على بيان، سيتم رفض البناء.

SDK الكبرى (Firebase, Adjust, AppsFlyer, Facebook SDK) قامت بالفعل بتحديث حزمها. إذا كان مشروعك يستخدم SDK غير معروف، تحقق من إصداره وإذا لزم الأمر قم بتحديثه أو اتصل بالمطور. الحل المؤقت هو إضافة بيان لـ SDK يدويًا في المشروع، ولكن هذا غير موصى به بسبب التناقضات أثناء التحديثات.

كيفية إنشاء Privacy Manifest في Xcode

يمكنك إنشاء PrivacyInfo.xcprivacy من خلال القالب المدمج في Xcode 15+ أو يدويًا. دعنا ننظر في كلا الخيارين.

الإنشاء عبر Xcode 15

يتضمن Xcode 15 قالب Privacy Manifest: File → New → File → Resource → Privacy Manifest. ينشئ Xcode ملفًا بهيكل أساسي ويملأ NSPrivacyTracking ومصفوفات فارغة لـ API والبيانات. بعد الإنشاء، تحتاج إلى تحديد الأسباب يدويًا لكل Required Reason API مستخدمة.

يضيف القالب تلقائيًا الملف إلى الهدف الرئيسي. إذا كان المشروع يحتوي على أهداف متعددة (Extensions, Watch app)، تحتاج إلى إضافة البيان إلى كل منها. لا يتحقق Xcode من وجود البيان في التبعيات في وقت الترجمة — فقط في مرحلة الأرشفة.

// AppDelegate: التحقق من البيان في مرحلة التطوير
import Foundation

func validatePrivacyManifest() {
    guard let path = Bundle.main.path(
        forResource: "PrivacyInfo", ofType: "xcprivacy"
    ) else {
        print("PrivacyInfo.xcprivacy غير موجود")
        return
    }
    guard let dict = NSDictionary(contentsOfFile: path)
    else { return }
    print("Privacy manifest loaded: \(dict.count) keys")
}

الإنشاء اليدوي عبر XML

يمكنك إنشاء PrivacyInfo.xcprivacy يدويًا كملف XML property list عادي. للقيام بذلك، أنشئ ملفًا باسم PrivacyInfo.xcprivacy، اكتب رأس plist القياسي وأضف قاموسًا جذرًا بالمفاتيح اللازمة. تأكد من إضافة الملف إلى الهدف (Target Membership).

الطريقة اليدوية مفيدة عندما تحتاج إلى إضافة بيان إلى مكتبة ثابتة أو تبعية Package Manager دون استخدام واجهة Xcode. بعد الترجمة، تحقق من تضمين الملف في الثنائي باستخدام أمر nm أو الأرشفة.

التحقق من البيان قبل النشر

قبل إرسال البناء إلى App Store، تحتاج إلى التحقق من أن Privacy Manifest صحيح وكامل. توفر Apple عدة أدوات تحقق.

المدقق المدمج في Xcode

عند أرشفة مشروع (Product → Archive)، يقوم Xcode بالتحقق من صحة البيانات. إذا تم العثور على خطأ — عدم وجود بيان، سبب غير صحيح، فئة فارغة — تفشل الأرشفة مع خطأ. يتم عرض سجل الأخطاء في Issue navigator مع الإشارة إلى SDK المشكلة وفئة API.

يتم إجراء تحقق إضافي على جانب App Store Connect عند تحميل البناء. إذا فشل التحقق، يتم رفض البناء مع بريد إلكتروني تلقائي يحتوي على معرف API المشكلة والإصلاح الموصى به.

التحقق عبر سطر الأوامر

لأتمتة التحقق، استخدم البرامج النصية التي تحلل الثنائي بحثًا عن استخدام Required Reason API. توفر Apple أداة libtool وبرامج نصية للتحقق من الرموز، لكن المجتمع طور أدوات أكثر ملاءمة.

# البحث عن استخدام API FileTimestamp في الثنائي
nm MyApp.app/MyApp | grep "NSFileCreationDate"

# التحقق من وجود PrivacyInfo.xcprivacy في التطبيق
find MyApp.app -name "*.xcprivacy"

أخطاء التحقق الشائعة

الخطأ الأكثر شيوعًا هو عدم وجود بيان في أحد SDK. حتى إذا كان الهدف الرئيسي يحتوي على بيان، تتحقق Apple من كل ثنائي على حدة. ثاني أكثر الأخطاء شيوعًا هو رمز سبب غير صحيح: استخدام سبب لفئة API مع API من فئة أخرى.

الخطأ الثالث هو الإعلان المفرط عن API التي لا تُستخدم فعليًا. يضيف المطورون جميع الأسباب الممكنة «احتياطًا»، مما يثير ريبة مراجعي Apple. أضف فقط الفئات المستخدمة فعليًا. استخدم المحلل الثابت لـ Xcode للتحقق.