كيفية تطبيق ملف PrivacyInfo.xcprivacy لتطبيقات ومكتبات iOS

كيف تطبق ملف PrivacyInfo.xcprivacy في تطبيقات iOS؟ يتطلب تطبيق PrivacyInfo.xcprivacy إضافة ملف بيان خصوصية صالح إلى هدف تطبيقك أو مكتبتك البرمجية (SDK)، والإعلان عن رموز الأسباب المعتمدة لأي واجهات برمجة تطبيقات ذات أسباب مطلوبة مستخدمة (مثل User Defaults أو وقت بدء تشغيل النظام)، والتحقق من أن التبعيات التابعة لجهات خارجية تلبي متطلبات بيان الخصوصية والتوقيع التي تنطبق على شكل توزيعها.

بيان الخصوصية (PrivacyInfo.xcprivacy) هو ملف قائمة خصائص معياري يتم تضمينه داخل تطبيقات iOS ومكتبات الأطراف الثالثة، حيث يعلن عن فئات جمع البيانات، وإعدادات نطاقات التتبع، والمبررات المعتمدة للوصول إلى واجهات برمجة التطبيقات ذات الأسباب المطلوبة التي تحددها Apple. بدءاً من 1 مايو 2024، يجب أن تتضمن التطبيقات المقدمة إلى App Store Connect أسباباً مععتمدة لواجهات برمجة التطبيقات ذات الأسباب المطلوبة المستخدمة بواسطة كود التطبيق، بما في ذلك كود مكتبات الأطراف الثالثة المعنية.

فهم متطلبات بيان خصوصية Apple لمكتبات iOS

هندسة بيانات الخصوصية: بيان التطبيق الرئيسي مقابل بيانات المكتبات المضمنة

يُنشئ إطار عمل بيان الخصوصية من Apple نموذج شفافية معياري عبر سلسلة توريد برمجيات iOS. بدلاً من مطالبة التطبيق المُضيف بالتدقيق اليدوي والإعلان عن تفاصيل التنفيذ الداخلي لكل مكتبة مُستوردة، تقسم Apple حوكمة الخصوصية إلى طبقات مميزة:

• بيان التطبيق الرئيسي: يغطي جمع البيانات المباشرة، ونطاقات التتبع على مستوى التطبيق، واجهات برمجة التطبيقات ذات الأسباب المطلوبة التي يتم استدعاؤها مباشرة بواسطة كود هدف التطبيق الأساسي.
• بيانات المكتبات المُضمنة: يجب أن تكون إعلانات واجهات برمجة التطبيقات ذات الأسباب المطلوبة مملوكة لكود التطبيق أو مكتبة الطرف الثالث التي تستخدم واجهات برمجة التطبيقات هذه. بالنسبة للملفات القابلة للتنفيذ والمكتبات الديناميكية، يجب أن تتضمن الحزمة التي تحتوي على هذا الملف القابلي للتنفيذ أو المكتبة بيان الخصوصية ذي الصلة؛ ولا يمكن لمكتبة طرف ثالث الاعتماد على بيان التطبيق المُضيف للإبلاغ عن استخدام المكتبة لواجهات برمجة التطبيقات ذات الأسباب المطلوبة.
• التجميع التلقائي للتبعيات: عند أرشفة التطبيق في Xcode 15 أو أحدث، يقوم نظام البناء بتمرير شبكة التبعيات، واكتشاف جميع ملفات PrivacyInfo.xcprivacy المُضمنة، وتجميعها في تقرير خصوصية موحد واحد.

مفاتيح التكوين الجذرية الأربعة

تم تنظيم كل ملف PrivacyInfo.xcprivacy كقاموس قائمة خصائص XML يحتوي على ما يصل إلى أربعة مفاتيح على مستوى الجذر:

• NSPrivacyTracking (قيمة منطقية - Boolean): يعلن عما إذا كان التطبيق أو المكتبة تستخدم البيانات التي تم جمعها من التطبيق للتتبع بموجب تعريفات شفافية تتبع التطبيقات من Apple (ATT).
• NSPrivacyTrackingDomains (مصفوفة من السلاسل النصية): تسرد نطاقات الإنترنت التي يتصل بها التطبيق أو المكتبة والتي تشارك في التتبع. إذا لم يمنح المستخدم إذن ATT، يقوم نظام iOS بحظر اتصالات الشبكة بالنطاقات المعلن عنها في هذه المصفوفة. إذا كان التطبيق أو المكتبة لا يتصلان بنطاقات التتبع، فيمكن تخطي هذا المفتاح.
• NSPrivacyCollectedDataTypes (مصفوفة من القواميس): تُبلغ عن الفئات المحددة من قِبل Apple للبيانات التي يجمعها التطبيق أو المكتبة عن الأشخاص الذين يستخدمون التطبيق، إلى جانب ما إذا كانت البيانات مرتبطة بهوية المستخدم، وما إذا كانت تُستخدَم للتتبع، والأغراض التشغيلية التي جُمعت من أجلها.
• NSPrivacyAccessedAPITypes (مصفوفة من القواميس): تعلن عن واجهات برمجة التطبيقات ذات الأسباب المطلوبة التي تحددها Apple والمُستدعاة بواسطة الملف الثنائي، مصحوبة برموز أسباب نصية معتمدة.

إنفاذ استيعاب App Store Connect وتشخيص الأخطاء

يقوم متجر App Store Connect بفرض بيانات الخصوصية أثناء استيعاب الملفات الثنائية:

• إعلان API مفقود (ITMS-91053): يُطلق عندما يقوم ملف ثنائي مُجمّع أو مكتبة مرتبطة باستدعاء رمز API ذي أسباب مطلوبة، ولكن مفتاح الفئة المقابل مفقود من NSPrivacyAccessedAPITypes.
• إعلان رمز سبب غير صالح: يحدث عندما يعلن البيان عن سلسلة أسباب غير معتمدة أو غير صالحة أو قديمة لفئة API معينة.
• بيان مكتبة طرف ثالث مطلوب مفقود: يتم فرضه في سيناريوهات التقديم التي تحددها متطلبات مكتبات الأطرف الثالثة الحالية من Apple للمكتبات المدرجة، مما يتطلب كلاً من بيانات الخصوصية والتوقيعات الرقمية الصالحة للتوزيع الثنائي.

يمكن للمطورين الذين يدمجون إسناد العملاء والروابط العميقة الرجوع إلى وثائق تكامل SDK الخاصة بـ iOS للمواصفات التقنية المتعلقة بإعلانات البيان.

انظر أيضاً: نظام iOS SDK ──> بنية إسناد الأجهزة المحمولة

فئات واجهات برمجة التطبيقات ذات الأسباب المطلوبة ورموز الأسباب المعتمدة

فئات واجهات برمجة التطبيقات الخمس ذات الأسباب المطلوبة

وفقاً لـ مذكرة تقنية مطوري Apple TN3183، تُعرّف Apple خمس فئات محددة من واجهات برمجة التطبيقات التي تتطلب رموز مبررات صريحة في NSPrivacyAccessedAPITypes. تتفاعل مكتبات الأجهزة المحمولة وتطبيقات iOS عادةً مع أربع فئات رئيسية:

• NSPrivacyAccessedAPICategoryUserDefaults: الوصول إلى إعدادات التطبيق المحلية عبر UserDefaults أو NSUserDefaults.
• NSPrivacyAccessedAPICategorySystemBootTime: قياس الوقت المنقضي أو طوابع الوقت باستخدام واجهات برمجة تطبيقات بدء تشغيل النظام مثل sysctl(KERN_BOOTTIME) أو systemUptime.
• NSPrivacyAccessedAPICategoryDiskSpace: فحص سعة نظام الملفات عبر statfs أو statvfs أو volumeAvailableCapacityKey.
• NSPrivacyAccessedAPICategoryFileTimestamp: التحقق من تواريخ إنشاء الملفات أو تعديلها عبر stat أو getattrlist أو contentModificationDateKey.
• NSPrivacyAccessedAPICategoryActiveKeyboards: فحص امتدادات لوحة المفاتيح المخصصة النشطة (تُستخدم أساساً بواسطة أدوات لوحة المفاتيح المتخصصة).

تعيينات رموز الأسباب المعتمدة لحالات الاستخدام الشائعة للمكتبات

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

إنشاء نموذج لقائمة خصائص PrivacyInfo.xcprivacy

تكوين أنواع جمع البيانات

تقوم مصفوفة NSPrivacyCollectedDataTypes بالإبلاغ عن فئات البيانات المحددة من قِبل Apple التي يجمعها التطبيق أو المكتبة عن الأشخاص الذين يستخدمون التطبيق، إلى جانب ما إذا كانت البيانات مرتبطة بهوية المستخدم، وما إذا كانت تُستخدَم للتتبع، والأغراض التشغيلية التي جُمعت من أجلها:

• NSPrivacyCollectedDataType: معرف السلسلة النصية القياسي لـ Apple (مثل NSPrivacyCollectedDataTypeDeviceID).
• NSPrivacyCollectedDataTypeLinked: قيمة منطقية تشير إلى ما إذا كانت البيانات مرتبطة بهوية المستخدم الفردي.
• NSPrivacyCollectedDataTypeTracking: قيمة منطقية تشير إلى ما إذا كانت البيانات تُستخدَم لتتبع عبر التطبيقات.
• NSPrivacyCollectedDataTypePurposes: مصفوفة من سلاسل الأغراض القياسية (مثل NSPrivacyCollectedDataTypePurposeAnalytics).

الإعلان عن نطاقات التتبع

إذا شاركت مكتبة أو تطبيق في التتبع بموجب تعريفات ATT، فيجب الإعلان عن جميع نطاقات التتبع المقابلة ضمن NSPrivacyTrackingDomains. إذا لم يتم منح إذن التتبع من قبل المستخدم، يقوم نظام iOS بحظر اتصالات الشبكة بالنطاقات المعلن عنها. وإذا كان التطبيق أو المكتبة لا يشاركان في التتبع، فيجب ضبط 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

عند دمج التبعيات عبر 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 الثابتة معاً داخل إطار عمل ثابت (Static Framework).
• تُنشئ بعض عمليات دمج CocoaPods بدلاً من ذلك أهداف حزمة موارد منفصلة لتوزيع الموارد إلى جانب المكتبات الثابتة.
• قد يرث بعض أهداف حزم الموارد التي تم إنشاؤها بواسطة CocoaPods تكوينات توقيع تسبب توقف عمليات بناء Xcode طالبةً فريق تطوير. تعتبر هذه مشكلة تكامل في نظام الإنشاء وليست مطلباً لمخطط PrivacyInfo.xcprivacy.

تطبيق حلول نظام الإنشاء المستهدفة في ملف Podfile

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

يوضح برنامج Ruby النصي أدناه كيفية التكرار عبر أهداف CocoaPods وتعطيل التقويع على أهداف حزم الموارد المحددة:

post_install do |installer|
  # Specify non-executable resource bundle targets that encounter signing errors without a development team
  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|
        # Strip code signing requirement from designated non-executable resource bundles
        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 الناتج للتأكد من ظهور كافة واجهات برمجة التطبيقات ذات الأسباب المطلوبة، وفئات البيانات، وبيانات مكتبات الطرف الثالث بدقة.

التحليل الثابت لسطر الأوامر: فحوصات الاستدلال المسبقة للتقديم

يمكن لفرق التطوير تنفيذ عمليات تدقيق استدلالية مسبقة للتقديم داخل خطوط الدمج والتسليم المستمر (CI/CD) عن طريق فبحث الملفات الثنائية المُجمّعة بحثاً عن الرموز المقيدة باستخدام nm و otool:

# Scan unpacked application binary for candidate Required Reason API symbols
nm -u /path/to/Payload/YourApp.app/YourApp | grep -E 'sysctl|statfs|statvfs|getattrlist|NSUserDefaults'

# Check embedded frameworks and bundles for PrivacyInfo.xcprivacy manifests
find /path/to/Payload/YourApp.app -name "PrivacyInfo.xcprivacy"

لا يُنشئ وجود الرموز بمفرده السبب المعتمد الذي ينطبق؛ راجع مسار الاستدعاء الفعلي وحالة الاستخدام قبل تعديل البيان. يجب على الفرق استخدام ميزة Generate Privacy Report في Xcode وفحوصات App Store Connect المسبقة للتحقق الرسمي.

مصفوفة التشخيص: الأسباب الجذرية لرفض بيان خصوصية App Store

الملخص وإطار اتخاذ القرار

يفرض إطار عمل بيان الخصوصية من Apple الشفافية عبر سلسلة توريد برمجيات iOS. يتطلب ضمان عمليات تقديم خالية من المشكلات إلى متجر App Store قيام فرق التطوير بتدقيق الكود المباشر بحثاً عن استخدام واجهات برمجة التطبيقات ذات الأسباب المطلوبة، والتحقق من أن تبعيات مكتبات الطرف الثالث تلبي متطلبات بيان الخصوصية القابلة للتطبيق على استخدامها لواجهات برمجة التطبيقات، وإدارة توقيع حزمة موارد CocoaPods بشكل مناسب.

للحصول على إعلانات بيان الخصوصية الخاصة بالمنتجات، راجع وثائق OpoInstall وقارن البيان المشحون مع التكامل الفعلي للتطبيق ومتطلبات Apple الحالية.

المواد ذات الصلة

• المفاهيم: بيانات الخصوصية، واجهات برمجة التطبيقات ذات الأسباب المطلوبة، توقيع حزمة الموارد، تقارير الخصوصية، الامتثال لمتجر App Store

• التقنيات: Xcode 15+، مدير تبعيات CocoaPods، مدير حزم Swift، مكتبة OpoInstall iOS SDK

• المعايير: مواصفات بيان الخصوصية من Apple، إرشادات مراجعة App Store القسم 5.1.1

• واجهات برمجة التطبيقات والتكوينات: PrivacyInfo.xcprivacy، NSPrivacyAccessedAPITypes، خطاف Podfile post_install

الوثائق الرسمية

• وثائق مطوري Apple حول وصف استخدام واجهات برمجة التطبيقات ذات الأسباب المطلوبة

• وثائق مطوري Apple حول ملفات بيان الخصوصية

• وثائق مطوري Apple حول متطلبات مكتبات الطرف الثالث القادمة

• إرشادات مراجعة متجر تطبيقات Apple القسم 5.1.1