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ها برای برداشتن اثر انگشت دستگاه بدون نیاز آشکار استفاده می‌کردند — مثلاً زمان uptime را برای تعیین منطقه زمانی می‌خواندند یا دایرکتوری‌ها را برای جمع‌آوری متادیتا اسکن می‌کردند. 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)، الزام (NSPrivacyCollectedDataTypeLinked)، هدف (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، User ID)، داده‌های استفاده (لاگ‌ها، کلیک‌ها)، تشخیص (crash logs) و محتوای کاربر (عکس، ویدیو، فایل‌ها). هر دسته به صورت اضافی به عنوان «مرتبط با کاربر» (linked) یا «غیرمرتبط» (not linked) علامت‌گذاری می‌شود.

Linked به این معنی است که داده‌ها با حساب کاربر مرتبط هستند؛ not linked — داده‌ها تجمیع یا ناشناس شده‌اند. بسته به این علامت‌گذاری، Apple برچسب حریم خصوصی را نمایش می‌دهد: داده‌های linked با رنگ زرد، not linked با رنگ سبز مشخص می‌شوند.

کدام 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 (اندازه‌گیری زمان جلسه برای تحلیل). هر استفاده دیگری به عنوان fingerprinting تلقی می‌شود.

لیست کامل دسته‌بندی‌های API

• FileTimestamp — دسترسی به برچسب‌های زمانی فایل‌ها، مجاز برای همگام‌سازی و پشتیبان‌گیری
• DiskSpace — بررسی فضای خالی، مجاز برای مدیریت حافظه نهان و دانلودها
• SystemBootTime — زمان uptime، فقط برای تحلیل جلسات مجاز است
• UserDefaults — دسترسی به UserDefaults برنامه‌های دیگر، کاملاً ممنوع
• ActiveKeyboards — لیست صفحه‌کلیدهای فعال، مجاز برای توسعه‌دهندگان IME
• SystemAperture — اندازه بریدگی صفحه، مجاز برای برنامه‌های عکس و AR

هر دسته‌بندی بین 1 تا 5 دلیل تأییدشده دارد. توسعه‌دهنده موظف است دلیلی را انتخاب کند که بیشتر با استفاده واقعی از API مطابقت دارد. ارائه دلیل نادرست می‌تواند منجر به رد بیلد یا مسدود شدن حساب شود.

الزامات برای SDKهای شخص ثالث

از 1 می 2024، تمام SDKهای شخص ثالث — چه باینری و چه متن‌باز — موظفند Privacy Manifest را در بسته خود قرار دهند. Apple مانیفست‌ها را برای همه وابستگی‌ها بررسی می‌کند و اگر حداقل یک SDK مانیفست نداشته باشد، بیلد رد می‌شود.

SDKهای بزرگ (Firebase, Adjust, AppsFlyer, Facebook SDK) قبلاً بسته‌های خود را به‌روز کرده‌اند. اگر پروژه شما از SDK کمتر شناخته‌شده‌ای استفاده می‌کند، نسخه آن را بررسی کنید و در صورت لزوم به‌روزرسانی کنید یا با توسعه‌دهنده تماس بگیرید. راه‌حل موقت — اضافه کردن دستی مانیفست برای SDK به پروژه، اما به دلیل عدم تطابق در به‌روزرسانی‌ها توصیه نمی‌شود.

ایجاد Privacy Manifest در Xcode

Privacy Info.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 not found")
        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 و اسکریپت‌های بررسی نمادها را ارائه می‌دهد، اما جامعه ابزارهای راحت‌تری توسعه داده است.

# جستجوی استفاده از FileTimestamp API در باینری
nm MyApp.app/MyApp | grep "NSFileCreationDate"

# بررسی وجود PrivacyInfo.xcprivacy در برنامه
find MyApp.app -name "*.xcprivacy"

خطاهای رایج اعتبارسنجی

رایج‌ترین خطا — عدم وجود مانیفست در یکی از SDKها. حتی اگر تارگت اصلی مانیفست داشته باشد، Apple همه باینری‌ها را جداگانه بررسی می‌کند. دومین خطای رایج — کد دلیل نادرست: استفاده از دلیل یک دسته‌بندی API با API از دسته‌بندی دیگر.

سومین خطا — اعلام بیش از حد APIهایی که در واقع استفاده نمی‌شوند. توسعه‌دهندگان همه دلایل ممکن را «برای احتیاط» اضافه می‌کنند که بازبینان Apple را نگران می‌کند. فقط دسته‌بندی‌هایی را اضافه کنید که واقعاً استفاده می‌شوند. از تحلیلگر استاتیک Xcode برای بررسی استفاده کنید.