كيفية إنشاء Android Keystore (دليل خطوة بخطوة)

الـ keystore هو ملف مشفّر يحتوي على زوج المفاتيح الخاص/العام المستخدم لتوقيع التطبيق. تشترط Google Play أن يحمل كل ملف AAB تقوم برفعه توقيعًا صالحًا؛ وأي حزمة غير موقّعة أو موقّعة بشكل خاطئ يتم رفضها من Play Console عند الرفع.

ينشئ Flutter وAndroid Studio تلقائيًا "debug keystore" لأغراض التطوير المحلي؛ يأتي بكلمة مرور ثابتة، ومخصص فقط للاختبار على جهازك الخاص، ولا يقبله أي متجر. أما الحزمة التي ترفعها إلى متجر ما فيجب توقيعها بـ keystore من نوع "release" أو "upload" تُنشئه بنفسك.

يجب توقيع كل تحديث لاحق لنفس التطبيق بنفس المفتاح (أو بسلسلة توقيع تعترف بها Google)؛ وإلا رفض Play Console التحديث بحجة "موقّع بشهادة مختلفة"، مما يجبر المستخدمين على إلغاء التثبيت وإعادته. هذا يجعل ملف الـ keystore جزءًا دائمًا من هوية تطبيقك.

keytool أداة سطر أوامر مرفقة مع Java Development Kit (JDK)؛ وبما أن تثبيت Flutter أو Android Studio لديك يتضمن JDK بالفعل، فعادةً لا تحتاج إلى تثبيت منفصل. الأمر القياسي الموصى به في توثيق Flutter الرسمي هو: keytool -genkey -v -keystore upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload. خيار -storetype JKS مهم هنا: فمنذ Java 9، أصبح نوع المخزن الافتراضي لـ keytool هو PKCS12، وبدون هذا الخيار سيحمل الملف الناتج امتداد .jks لكن محتواه سيكون فعليًا بصيغة PKCS12.

يحدد -keyalg RSA -keysize 2048 خوارزمية المفتاح وطوله، ويجعل -validity 10000 المفتاح صالحًا لنحو 27 عامًا، أما -alias upload فهو الاسم المختصر الذي تمنحه للمفتاح وستعيد استخدامه في key.properties. عند تشغيل الأمر، سيُطلب منك بالترتيب كلمة مرور المخزن (store password)، ثم كلمة مرور المفتاح (key password)، ثم بيانات اسمك/مؤسستك.

على macOS وLinux، يعمل keytool مباشرة من الطرفية إذا كان JDK ضمن PATH. أما على Windows، فشغّل أولًا flutter doctor -v وابحث عن سطر "Java binary at:" في مخرجاته لمعرفة أي JDK يُستخدم بالضبط؛ يوجد keytool داخل مجلد bin ضمن ذلك الدليل (إذا لم يكن JAVA_HOME معرَّفًا، أو كان لديك أكثر من JDK مثبّت، فافتراض المسار "%JAVA_HOME%\bin\keytool" قد يشير إلى JDK خاطئ). اضبط مسار الملف في المعامل -keystore ليطابق دليل المستخدم الخاص بك، ودوّن الدليل الذي شغّلت منه الأمر — ستحتاج إلى هذا المسار مرة أخرى في الخطوة التالية.

أنشئ ملفًا باسم key.properties داخل android/ وأضف السطور الخاصة بـ storePassword وkeyPassword وkeyAlias وstoreFile (المسار الكامل لملف الـ keystore الخاص بك). هذا الملف نص عادي ويحمل كلمات مرورك بشكل صريح، لذا يجب ألا يُدرج أبدًا ضمن نظام التحكم بالإصدارات — أضف سطر key.properties إلى .gitignore كأول خطوة على الإطلاق.

في android/app/build.gradle.kts (لغة Kotlin DSL الحالية)، تقرأ هذا الملف وتُعرّف كتلة signingConfigs.release، مع أخذ keyAlias وkeyPassword وstoreFile وstorePassword من key.properties. ثم تُسند signingConfig = signingConfigs.getByName("release") إلى نوع البناء release بحيث تُوقَّع كل حزمة release يتم إنتاجها بهذا المفتاح.

إذا كان تصغير R8/ProGuard مفعّلًا (isMinifyEnabled=true)، فاختبر حزمة الـ release الموقّعة على جهاز حقيقي قبل رفعها إلى المتجر؛ فبعض الحزم التي تعتمد على reflection تتأثر بالتصغير وتنهار فقط في بناء release. هذا لا علاقة له بالتوقيع نفسه، لكنه خطأ شائع يُنسى في نفس الخطوة.

منذ عام 2021، تشترط Google تفعيل Play App Signing على التطبيقات الجديدة، ولم يعد خيار إلغاء الاشتراك متاحًا. يتضمن هذا النموذج مفتاحين مختلفين: "upload key" الذي تُنشئه بـ keytool وتستخدمه لتوقيع كل AAB، و"app signing key" الذي تحتفظ به Google في بنيتها التحتية الآمنة الخاصة وتستخدمه لإضفاء التوقيع النهائي على الحزمة الموزَّعة على المستخدمين. أنت لا ترى أو تمتلك app signing key بنفسك أبدًا.

إذا فقدت upload key الخاص بك (الملف أو كلمات مروره) لكنك مسجّل في Play App Signing، فهناك مخرج: من داخل Play Console، انتقل إلى Protected with Play > Play Store protection > Manage Play app signing، ثم افتح طلب "Request upload key reset" من قسم "Upload Key Certificate". تسير العملية كالتالي: أنشئ upload keystore جديدًا باستخدام keytool، ثم صدّر شهادته بصيغة PEM باستخدام الأمر keytool -export -rfc -keystore upload-keystore.jks -alias upload -file upload_certificate.pem، ثم ارفع ملف PEM هذا إلى Play Console مع ملاحظة توضح سبب إعادة التعيين. بعد أن تراجع Google الطلب وتوافق عليه، يصبح upload key الجديد نشطًا؛ ولأن مفتاح التوقيع الفعلي لم يغادر يد Google قط، تبقى هوية تطبيقك في المتجر وتقييماته وعدد عمليات تثبيته دون تأثر.

إذا لم تشترك قط في Play App Signing — وهي الحالة النموذجية للتطبيقات القديمة المنشورة قبل أن يصبح إلزاميًا — وفقدت مفتاح التوقيع الوحيد لديك، فلا سبيل للرجوع: لن تتمكن أبدًا من رفع أي تحديث آخر لذلك التطبيق. الخيار الوحيد هو فتح قائمة جديدة تمامًا بمعرّف applicationId جديد، وهو ما يعني فقدان التقييمات الحالية وعدد التثبيتات وترتيب البحث.

الاحتفاظ بملف الـ keystore على قرص محلي واحد فقط أمر محفوف بالمخاطر: فتعطل القرص، أو إعادة الفورمات، أو تغيير الحاسوب قد يفقد الملف بشكل نهائي. احتفظ بنسخة احتياطية مشفّرة واحدة على الأقل (قرص خارجي، تخزين سحابي مشفّر)، ولا تُضِف الملف أبدًا إلى مستودع مشروعك — فمثل key.properties، يجب أن يكون ملف الـ keystore أيضًا ضمن .gitignore.

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

تخزّن خزنة Keystore من Vibeloy ملف الـ keystore وكلمات المرور الخاصة بك بتشفير من طرف إلى طرف؛ فبدلًا من الاحتفاظ بالملف كنسخة محلية وحيدة، يمكنك حفظه بأمان في خزنة مرتبطة بحسابك يمكن الوصول إليها من أي جهاز. هذه ميزة premium في Vibeloy.