شهادة مطور iOS وملف provisioning profile مع Expo

تثبت شهادة مطور iOS من وقّع تطبيقك. أما ملف provisioning profile، أي ملف التزويد، فيربط هذه الشهادة بتطبيق محدد ويحدد أين يُسمح له بالعمل. مع Expo، لن تحتاج تقريبًا أبدًا إلى إنشائهما يدويًا: تنشئهما EAS وتخزنهما وتجددهما عندما تطلق build.

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

أنشر تطبيقاتي على iOS باستخدام Expo وEAS، ومنها Solys وTradaZen. المسار الكامل موجود في نشر تطبيق iOS بدون Mac. هنا، نفتح غطاء التوقيع.

لماذا تشترط Apple التوقيع

يجب أن يكون تطبيق iOS موقّعًا حتى يُثبَّت على iPhone أو يُرسل إلى App Store Connect. يضمن التوقيع أن التطبيق صادر عن مطور تعرفه Apple وأن أحدًا لم يعدّله منذ ذلك الحين.

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

العناصر الأربعة التي يجب معرفتها

يذكر توثيق Expo حول بيانات الاعتماد ثلاثة عناصر لـ iOS: شهادة التوزيع، والملفات، ومفتاح الإشعارات الفورية. وأضيف إليها معرّف التطبيق، الذي لا يوجد أي ملف بدونه.

شهادة التوزيع

هي توقيعك كمطور. يميّز دليل Apple حول الشهادات بين عائلتين:

• Apple Development لتشغيل تطبيقك على أجهزتك أثناء التطوير. وهي تخص شخصًا واحدًا.
• Apple Distribution للتوزيع على أجهزة اختبار محددة أو للإرسال إلى App Store Connect. وهي تخص الفريق، ولا يستطيع إنشاءها إلا صاحب الحساب أو مسؤول (admin).

لا تخص شهادة التوزيع أي تطبيق بعينه: الشهادة نفسها توقّع كل تطبيقاتك. وترافقها مفتاح خاص، وهو ما يتيح التوقيع. وفقًا لـ TN3161، تكون شهادة Apple صالحة عمومًا لمدة سنة من تاريخ إنشائها.

معرّف التطبيق (App ID)

يعرّف App ID تطبيقك داخل الملف. وهو يأخذ معرّف الحزمة (bundle identifier)، مثل com.example.myapp (مثال وهمي). ووفقًا لدليل Apple، يحمل أيضًا قائمة القدرات المسموح بها: الإشعارات الفورية، وApp Groups، وSign in with Apple…

مع Expo، هو الحقل ios.bundleIdentifier في إعداداتك. اختره مرة واحدة وإلى الأبد: يجب أن يكون متطابقًا في كل مكان، في إعداداتك كما في App Store Connect. لا تنتهي صلاحية App ID. ووفقًا لتوثيق Expo حول قدرات iOS، تزامن EAS قدراته مع إعداداتك في كل build.

ملف التزويد

الملف هو حلقة الوصل. يحتوي على App ID وشهادة، وحسب نوعه، قائمة بالأجهزة المسموح بها. ثلاثة أنواع تهمك:

• Development: تطبيق الاختبار على أجهزتك المسجلة.
• Ad hoc: build قابل للتثبيت على قائمة محددة من الأجهزة، كل منها معرّف بـ UDID الخاص به. وهو «التوزيع الداخلي» في EAS.
• App Store: لـ App Store Connect وTestFlight. لا يحتوي على أي قائمة أجهزة، كما توضح الملاحظة TN3125.

لكل ملف تاريخ انتهاء: لا يتجاوز سنة عمومًا وفقًا لـ Apple، و12 شهرًا وفقًا لـ Expo.

مفتاح الإشعارات الفورية (APNs)

يسمح مفتاح APNs لخادمك، أو لخادم Expo، بإرسال إشعارات إلى تطبيقك. وهو ملف ‎.p8 لا يمكن تنزيله إلا مرة واحدة: Apple لا تحتفظ به في حسابك. المفتاح نفسه يخدم كل تطبيقاتك، ولا تنتهي صلاحيته أبدًا.

الجدول الملخص

العنصر	الغرض	المدة	من يديره مع Expo
شهادة التوزيع	توقيع الـ builds	سنة عمومًا	EAS، بعد تسجيل الدخول
App ID	تعريف تطبيقك	بلا انتهاء صلاحية	أنت، ثم EAS
ملف App Store	الإرسال إلى Apple	حتى 12 شهرًا	EAS
ملف ad hoc	التثبيت على أجهزة iPhone لديك	حتى 12 شهرًا	EAS وأجهزتك
مفتاح APNs	إرسال الإشعارات	بلا انتهاء صلاحية	EAS أو أنت
ملف الحساب المجاني	الاختبار عبر Xcode	7 أيام	Xcode، لا EAS

«أنت، ثم EAS»: تختار معرّف الحزمة، وتتولى EAS القدرات. «EAS وأجهزتك»: تسجّل كل iPhone اختبار، وتصنع EAS الملف. السطر الأخير يخص حساب Apple المجاني: وفقًا لدليل Apple حول الحسابات، تنتهي صلاحية ملفاته بعد 7 أيام من إنشائها.

حدود Apple التي يجب معرفتها

• شهادات التوزيع: عدد قليل جدًا لكل حساب. يتحدث دليل Apple عن شهادة واحدة لكل نوع توزيع ولكل فريق، وجدول Expo عن حد أقصى 2. احفظ القاعدة: لا تنشئ شهادة جديدة مع كل build أو على كل حاسوب.
• مفاتيح APNs: 2 لكل حساب كحد أقصى، وفقًا لـ Expo.
• الملفات: بلا حد، وفقًا لـ Expo.
• الأجهزة: حتى 100 لكل عائلة منتجات ولكل سنة عضوية، وفقًا لدليل Apple حول الأجهزة. تعطيل جهاز لا يحرر مكانًا. يعود العداد إلى 100 في بداية سنة العضوية التالية، إذا أزلت الأجهزة.

ما تفعله EAS نيابةً عنك

وفقًا لصفحة Expo حول بيانات الاعتماد المُدارة، يعرض عليك أول build لـ iOS إنشاء ما ينقص. تسجّل الدخول إلى حساب Apple Developer، فتنشئ EAS شهادة التوزيع والملف ومفتاح الإشعارات، ثم تخزنها على خوادمها. وتعيد الـ builds التالية استخدامها.

ثلاث نقاط مفيدة:

• كلمة مرور Apple تبقى على جهازك. توضح صفحة الأمان لدى Expo أنها لا تُرسل إلى خوادمها، وأن بيانات الاعتماد المخزنة مشفرة.
• eas credentials يعرض لك كل شيء: الشهادة، والملفات، ومفتاح الإشعارات. ويتيح الأمر أيضًا استبدالها أو إزالتها.
• الحذف من EAS لا يحذف لدى Apple. لتحرير مكان، يجب الإلغاء (revoke) في بوابة Apple.

يمكنك أيضًا الاحتفاظ بالتحكم عبر بيانات الاعتماد المحلية: ملف credentials.json يشير إلى شهادتك (‎.p12) وملفك (‎.mobileprovision). تطلب Expo إضافة هذه الملفات إلى .gitignore. إنها القاعدة نفسها المتبعة مع مفاتيح API في تطبيق Expo: السر لا يذهب أبدًا إلى المستودع.

الأخطاء الشائعة وكيف تحلها

ملف منتهي الصلاحية

يحمل build الـ ad hoc ملفه بداخله: عند انتهاء صلاحيته، لا يعود التطبيق يفتح على أجهزة iPhone الاختبارية لديك. أما على App Store، فتؤكد Expo أن انتهاء الصلاحية لا يؤثر إطلاقًا على التطبيق في الإنتاج. الحل: أطلق build جديدًا. تنشئ EAS ملفًا جديدًا، أو تفعل ذلك بنفسك عبر eas credentials. ثم أعد تثبيت الـ build الجديد على أجهزتك.

لا تخلط ذلك مع TestFlight: تنتهي صلاحية build في TestFlight بعد 90 يومًا، مهما كانت شهادتك. التفاصيل في TestFlight لاختبار تطبيق iPhone.

شهادة منتهية أو ملغاة

موقف Apple واضح: إذا كانت عضويتك سارية، فلن تتأثر تطبيقاتك الموجودة على App Store. لكنك لن تستطيع إرسال build موقّع بهذه الشهادة. وقد يُوسم build أُرسل ولم يُقدَّم بعد بالحالة Invalid Binary إذا أُلغيت شهادته. كما أن الملفات التي تحتوي على شهادة ملغاة تصبح غير صالحة.

الحل: أنشئ شهادة جديدة من eas credentials أو عند الـ build التالي، ثم دع EAS تعيد إنشاء الملفات. ولا تلغِ أبدًا بشكل تلقائي شهادة تعمل.

جهاز غير موجود في ملف ad hoc

رابط التثبيت يعمل لديك، لكن ليس على iPhone أحد المختبرين. السبب: يوضح توثيق Expo حول التوزيع الداخلي أن الأجهزة الموجودة في الملف لحظة الـ build هي وحدها التي يمكنها تثبيت التطبيق.

الحل:

1. سجّل الجهاز باستخدام eas device:create.
2. أطلق build جديدًا في الوضع التفاعلي، مع تسجيل الدخول إلى حساب Apple، لتحدّث EAS الملف. أو أعد توقيع الـ build الحالي باستخدام eas build:resign، دون إعادة تجميع كل شيء.
3. في التكامل المستمر (CI)، يعيد الوضع غير التفاعلي استخدام الملف دون تحديث قائمته. أضف الخيار --refresh-ad-hoc-provisioning-profile.

على حساب جديد أو جُدّد للتو، قد تستغرق Apple من 24 إلى 72 ساعة لمعالجة جهاز جديد. لذلك قد يفشل أول build يتضمنه: انتظر، ثم أعد المحاولة.

بلوغ حد الشهادات

ترفض Apple إنشاء شهادة توزيع جديدة. غالبًا ما تكون هناك شهادات قديمة متروكة: أُنشئت من Xcode على Mac آخر أو من خدمة build أخرى. أعد استخدام الشهادة الموجودة إن كان لديك ملف ‎.p12 الخاص بها. وإلا، ألغِ الشهادة التي لم تعد مستخدمة في بوابة Apple. الإلغاء لا يؤثر على تطبيقاتك المنشورة، لكنه يُبطل الملفات التي كانت تحتويها.

«Provisioning profile doesn't include signing certificate»

تعني رسالة Xcode هذه أن الملف لا يحتوي على الشهادة التي يوجد مفتاحها الخاص على جهازك. السبب المعتاد: الخلط بين التوقيع التلقائي في Xcode وبيانات اعتماد EAS. اختر مصدرًا واحدًا للحقيقة: builds EAS مع بيانات اعتماد مُدارة، أو بيانات اعتماد محلية، لا الاثنين معًا.

توقف الإشعارات بعد إلغاء مفتاح

إذا ألغيت مفتاح APNs، تنبّه Expo إلى أن كل التطبيقات التي تستخدمه لن تتلقى إشعارات بعد الآن. أنشئ مفتاحًا جديدًا وارفعه عبر eas credentials. رموز Expo Push الخاصة بمستخدميك لا تتغير.

قدرة مضافة، ملف غير صالح

تفعيل خدمة مثل الإشعارات الفورية أو App Groups يجعل الملف غير صالح: يجب إعادة إنشائه. مع EAS، تتم مزامنة القدرات في كل build. إذا ظل الملف مرفوضًا، يتيح لك eas credentials إنشاء ملف جديد.

ما بعد التوقيع

الـ build الموقّع مجرد مرحلة. صفحة التطبيق، ولقطات الشاشة، والخصوصية، والإرسال للمراجعة، كلها مجمعة في نشر تطبيق على App Store. إن لم تكن لديك عضوية بعد، فابدأ بـ حساب مطور Apple. ولتفهم لماذا أنصح المبتدئين بـ Expo، اقرأ React Native وExpo لتطبيق جوال.

إذا كنت تحضّر لنشرك الأول

قبل أول إرسال، أجرِ التشخيص المجاني: يخبرك بما يعيق مشروعك فعلًا ويرسل إليك قائمتي للتحقق ضد رفض Apple.

لبناء التطبيق، وربط الاشتراكات، ونشره دون معاناة مع التوقيع، يرافقك iOS & Android Kit في مسار من أربع مراحل مع Starter Code لتطبيقاتي، وبالوتيرة التي تناسبك.

الأسئلة الشائعة

ما هو ملف provisioning profile؟

هو الملف الذي يسمح لتطبيقك بالعمل أو بالإرسال إلى Apple. يربط معرّف تطبيق وشهادة، وحسب نوعه، قائمة أجهزة. ملف App Store لا يحتوي على أي جهاز، وملف ad hoc يسرد بعض الأجهزة.

هل شهادة مطور iOS مجانية؟

ليس لها سعر منفصل: شهادة التوزيع مشمولة في Apple Developer Program، بسعر 99 $ سنويًا. مع حساب Apple مجاني، يتيح لك Xcode الاختبار على 3 أجهزة كحد أقصى، لكن الملفات تنتهي بعد 7 أيام والنشر مستحيل.

كم تدوم شهادة التوزيع من Apple؟

عمومًا سنة من تاريخ إنشائها، وفقًا لـ Apple. وتدوم ملفات التزويد أيضًا 12 شهرًا كحد أقصى. أما مفتاح الإشعارات الفورية فلا تنتهي صلاحيته أبدًا.

ماذا يحدث إذا انتهت صلاحية شهادة التوزيع؟

لا شيء بالنسبة لتطبيقاتك الموجودة على App Store، طالما أن عضويتك سارية. كل ما في الأمر أنك لن تستطيع إرسال build جديد موقّع بهذه الشهادة. مع EAS، تُنشأ شهادة جديدة عند الـ build التالي أو عبر eas credentials.

هل أحتاج إلى Mac لإنشاء شهادة iOS؟

لا، إذا استخدمت EAS. تسجّل الدخول إلى حساب Apple من سطر الأوامر، وتنشئ EAS الشهادة والملف، على Windows كما على Linux. بدون EAS، تمر الطريقة التقليدية عبر Xcode أو سلسلة المفاتيح (Keychain Access) على Mac.

كم جهازًا يمكن أن يحتوي ملف ad hoc؟

يمكن لحسابك تسجيل حتى 100 جهاز iPhone لكل سنة عضوية، والعدد نفسه لكل عائلة أجهزة أخرى. الجهاز المعطَّل يبقى محسوبًا. للاختبار مع عدد أكبر من الأشخاص، استخدم TestFlight.