تسجيل أسماء الحِزم باستخدام واجهة برمجة التطبيقات Android Developer Console API

‫Android Developer Console API هي واجهة عامة مصمَّمة للسماح لموزّعي التطبيقات والمطوّرين الأفراد بتسجيل أسماء الحِزم آليًا في Android Developer Console.

إمكانات الاتصال من خادم إلى خادم بصفتك:

موزّع التطبيقات	مطوِّر فردي
تسجيل اسم حزمة - مفتاح نيابةً عن المطوّر الذي ينشر تطبيقًا في المتجر تسجيل اسم حزمة باستخدام مفتاح يديره المتجر إثبات ملكية مفتاح مرتبط باسم حزمة	تسجيل اسم حزمة - مفتاح في سير عمل النشر المتواصل إثبات ملكية مفتاح مرتبط باسم حزمة

قبل البدء

قبل البدء، يجب أن يتوفّر لديك ما يلي:

1. إذن وصول إداري إلى مشروع على Google Cloud
2. فهم أساسي لما يلي:
   • واجهات برمجة تطبيقات RESTful
   • بنية حزمة APK
   • توقيع تطبيق Android
   • إنشاء ملخّصات SHA-256

يجب أيضًا أن تكون على دراية بالمصطلحات التالية:

العبارة	التعريف
حساب المطوِّر	تمثّل حسابًا على Android Developer Console يمكنه امتلاك اسم حزمة واحد أو أكثر. وتحتوي على حالة إثبات الهوية (NOT_VERIFIED أو VERIFIED).
اسم الحزمة	اسم حزمة Android معيّن (على سبيل المثال، com.example.app) ضمن حساب مطوّر، ويمكن ربطه بمفتاح واحد أو أكثر. ويحتوي على حالة تسجيل (DRAFT أو IN_REVIEW أو REGISTERED أو PENDING_TRANSFER).
المفتاح	الشهادة/المفتاح العام المحدّد المستخدَم لتوقيع اسم حزمة Android يتضمّن تجزئة SHA-256 وحالة التسجيل الحالية (DRAFT أو OWNERSHIP_VERIFIED أو IN_REVIEW أو REGISTERED أو PENDING_TRANSFER).

البدء

أكمِل الخطوات التالية للوصول إلى Android Developer Console API:

إنشاء مشروع على Google Cloud

1. أنشئ حسابًا على Google Cloud إذا لم يكن لديك حساب.
2. افتح Google Cloud Console.
3. أنشئ مشروعًا على Google Cloud.

تفعيل واجهة برمجة التطبيقات في مشروعك على Google Cloud

1. افتح Google Cloud Console.
2. في قائمة التنقّل (☰)، اختَر APIs & Services (واجهات برمجة التطبيقات والخدمات) > Library (المكتبة).
3. اختَر مشروع Google Cloud الذي تريد تفعيل واجهة برمجة التطبيقات فيه من القائمة المنسدلة للمشاريع.
4. استخدِم شريط البحث واجهات برمجة التطبيقات والخدمات لاختيار واجهة برمجة تطبيقات Android Developer Console.
5. فعِّل واجهة برمجة التطبيقات:
   1. انتقِل إلى صفحة النظرة العامة على واجهة برمجة التطبيقات من خلال اختيارها من نتائج البحث.
   2. انقر على الزر الأزرق "تفعيل". تفعّل Google Cloud واجهة برمجة التطبيقات لمشروعك المحدّد، ويستغرق ذلك عادةً بضع لحظات. بعد تفعيلها، يمكنك البدء في استخدامها.

مصادقة واجهة برمجة التطبيقات

لإجراء طلبات إلى واجهة برمجة التطبيقات Android Developer Console، عليك مصادقة طلباتك باستخدام OAuth 2.0.

المصادقة باستخدام OAuth 2.0

تتطلّب واجهة برمجة التطبيقات Android Developer Console API مصادقة OAuth 2.0 للسماح بالوصول إلى موارد حساب المطوّر وأسماء الحِزم. بما أنّ بيانات حساب المطوّر مرتبطة بحساب المستخدم على Google وليس بمشروع على Google Cloud، لا يمكن استخدام حسابات الخدمة واتحاد هوية أعباء العمل ومفاتيح واجهة برمجة التطبيقات لمصادقة طلبات البيانات من واجهة برمجة التطبيقات.

نطاق OAuth 2.0

النطاق التالي مطلوب لجميع العمليات:

نطاق OAuth 2.0	الوصف
https://www.googleapis.com/auth/androiddeveloperconsole	عرض أسماء الحِزم وبياناتها وإدارتها في حساباتك على Android Developer Console

تنفيذ مسار خادم الويب OAuth 2.0

للتكامل مع واجهة برمجة تطبيقات Android Developer Console، يجب أن تستخدم التطبيقات مسار خادم الويب OAuth 2.0. بناءً على نوع تطبيقك واحتياجاتك في مجال التشغيل الآلي، يمكنك الاختيار بين استراتيجيتَين رئيسيتَين لإدارة بيانات الاعتماد:

الخيار (أ) (يُنصح به): الوصول بلا إنترنت أو الوصول المبرمَج (التكامل المستمر/النشر المستمر وتكامل الخادم)

الخيار "ب": الوصول المؤقت أو التفاعلي

تسمح هذه الاستراتيجية بتشغيل العمليات المبرمَجة (مثل مسارات CI/CD) في الخلفية بدون تدخّل بشري: إعداد موافقة المستخدم لمرة واحدة: أثناء الإعداد الأولي، يُكمل المطوّر أو صاحب الحساب عملية الموافقة لمرة واحدة في المتصفّح. يطلب تطبيقك إذن التشغيل بلا إنترنت (access_type=offline) بالإضافة إلى نطاق واجهة برمجة التطبيقات. تُرجع Google رمز تفويض، يستبدله تطبيقك برمز دخول أولي ورمز مميز لإعادة التحميل طويل الأجل. التنفيذ في الخلفية: يمكنك تخزين refresh_token بأمان في بيئة النشر أو مدير كلمات المرور (مثل GitHub Actions Secrets أو Google Secret Manager). بالنسبة إلى طلبات البيانات اللاحقة من واجهة برمجة التطبيقات، يستخدم سير العمل المبرمَج الرمز المميز لإعادة التحميل المخزَّن للحصول على رمز مميز جديد للوصول قصير الأجل عند الطلب، ما يؤدي إلى تجاوز أي طلبات تسجيل دخول يدوي أو مصادقة ثنائية.

إذا كنت تفضّل تجنُّب تخزين الرموز المميزة لإعادة التحميل الطويلة الأمد في بيئتك، أو إذا كان تطبيقك يعمل في سياق مستخدم تفاعلي: الطلب عند التنفيذ: لا تطلب التشغيل بلا إنترنت أو تخزين رمز مميز لإعادة التحميل. في كل مرة يتم فيها تنفيذ الأداة أو التطبيق، اطلب من المستخدم المصادقة من خلال إعادة توجيهه إلى صفحة موافقة Google OAuth في المتصفّح. الوصول لفترة قصيرة: يسجّل المستخدم الدخول ويمنح الموافقة، ويتلقّى التطبيق رمز وصول لفترة قصيرة مباشرةً (أو باستخدام تبادل رمز التفويض). يُستخدَم رمز الوصول هذا لإجراء طلبات بيانات من واجهة برمجة التطبيقات ويتم تجاهله بعد التنفيذ. تتطلّب عمليات التشغيل المستقبلية من المستخدم إعادة المصادقة.

تسجيل اسم حزمة

تسجيل اسم الحزمة هو عملية ربط مفتاح باسم حزمة. تعتمد طريقة تسجيل المفتاح على ما إذا كنت تسجّل مفتاحًا لاسم حزمة جديد أو حالي في Android.

تسجيل اسم حزمة جديد

لتسجيل اسم حزمة جديد لم يسبق ظهوره على Android، يمكنك تقديم شهادة المفتاح العام من مفتاحا التشفير لتوقيع التطبيق.

تسجيل اسم حزمة حالي

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

إذا كان المفتاح الذي تسجّله مُدرجًا على أنّه "يتطلّب تقديم سبب"، سيظل بإمكانك تسجيله، ولكن بالإضافة إلى إكمال إثبات الملكية، على المطوّر أيضًا تقديم سبب لاستخدام اسم الحزمة.

قواعد الأهلية الرئيسية

تُحدَّد قائمة المفاتيح المؤهَّلة وفقًا لقواعد أهلية أسماء الحزم التي صُمّمت للحدّ من مشاركة اسم الحزمة، والتي تم تقديمها كجزء من عملية التحقّق من هوية مطوّري تطبيقات Android.

في الحالات التي يُستخدم فيها اسم الحزمة من قبل عدة مطورين أو يتضمّن مفاتيح توقيع متعددة، يتم تحديد الأهلية على النحو التالي:

السيناريو	قاعدة التسجيل المباشر	قاعدة المطوّرين الآخرين
المفتاح ذو الحصة الأكبر	تكون الأولوية للمفتاح الذي يمثّل أكثر من ‎50% من إجمالي عمليات التثبيت المعروفة.	وعلى جميع المطوّرين الآخرين تقديم مبرّر.
أكثر من 50 عملية تثبيت	إذا لم يمثّل أي مفتاح أكثر من ‎50% من عمليات التثبيت، تكون جميع المفاتيح المرتبطة بـ 50 عملية تثبيت أو أكثر مؤهَّلة.	على المطوّرين الذين ترتبط مفاتيحهم بأقل من 50 عملية تثبيت تقديم مبرّر.
أقل من 50 عملية تثبيت	إذا لم يستوفِ أي من المفاتيح الحدّ الأدنى البالغ 50 عملية تثبيت، يمكن استخدام أي مفتاح وفقًا لمبدأ الأسبقية	بعد تسجيل مطوّر واحد، يجب على الآخرين تقديم سبب.

إثبات ملكية المفتاح

لإكمال عملية إثبات صحة اسم حزمة حالي، توفّر واجهة برمجة التطبيقات سلسلة إثبات صحة. يجب تضمين سلسلة إثبات الملكية هذه داخل ملف جديد يُسمى adi-registration.properties داخل مجلد مواد عرض التطبيق. بعد ذلك، عليك توقيع حزمة APK وتحميلها باستخدام المفتاح الخاص المطابق للمفتاح العام الذي تسجّله.

توضيح سبب تسجيل المفتاح

إذا كان تسجيل المفتاح يتطلّب تقديم مبرّر، على المطوّرين تقديم سبب تجاري مفصّل. تراجع Google هذا السبب، ويمكن أن تستغرق الموافقة على تسجيل اسم الحزمة مدة تصل إلى 24 ساعة.

أفضل الممارسات المتعلّقة بتجربة المستخدم

ننصح بأن تتّبع التطبيقات التي تستخدم Android Developer Console API هذه الأنماط لضمان التكامل السلس.

تحديد سياق واضح لتفويض OAuth

يساعد تقديم سياق واضح قبل طلب تفويض OAuth المطوّرين في فهم سبب الحاجة إلى الوصول إلى الحساب. لتوجيه المستخدمين بشكل فعّال، قدِّم شرحًا واضحًا للوظيفة المتوقّعة قبل عرض شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth.

يمكنك تنظيم سياق التفويض باستخدام التنسيق التالي:

• العنوان: "ربط حسابك على Android Developer Console"
• الملخّص: "إدارة تسجيل أسماء الحِزم للتحقّق من هوية مطوّري تطبيقات Android في [application-name]"
• زر الإجراء: زر "المتابعة باستخدام حساب Google" أو "تسجيل الدخول باستخدام حساب Google"

تحديد حسابات المطوّرين

1. يمكنك التكامل مع طريقة واجهة برمجة التطبيقات ListDeveloperAccounts لاسترداد جميع حسابات المطوّرين التي تم السماح بالوصول إليها وإدراجها.
2. يجب توفير منتقي حسابات للسماح للمطوّر باختيار حساب المطوّر المفضّل لديه.
3. يجب عرض الحساب displayName بشكل بارز، باستخدام رقم الحساب من الحقل name كمعلومات ثانوية.
4. عرض حالات التحقّق من الحساب (verificationState):
   • VERIFIED: تأكيد هوية المطوّر الذي تم التحقّق منه باستخدام إشارة مرئية إيجابية (مثل علامة صح خضراء)
   • ‫NOT_VERIFIED: تشير إلى أنّ عملية التحقّق غير مكتملة، ويتم حظر تسجيل الحِزم للحساب. يمكنك اختياريًا توفير زر أساسي للحث على اتخاذ إجراء يوجّه المطوّرين إلى Android Developer Console عند اختيار الحساب.

إذا تم تلقّي ردّ فارغ بسبب عدم ارتباط أي حسابات مطوّرين بحساب Google، يجب توجيه المطوّرين إلى Android Developer Console باستخدام زر أساسي للحث على اتخاذ إجراء.

إدارة أسماء الحِزم

1. يمكنك التكامل مع نقطة نهاية واجهة برمجة التطبيقات ListAndroidPackages لاسترداد جميع أسماء الحزم المرتبطة بحساب المطوّر. توفير واجهة مركزية للمطوّرين، مثل قائمة أو جدول، لمراقبة حالات الحِزم بفعالية
2. عرض packageName إلى جانب حالة التسجيل الحالية (DRAFT أو IN_REVIEW أو REGISTERED أو PENDING_TRANSFER)، مع تطبيق مؤشرات مرئية مميزة لكل حالة. إذا تم تقديم "اسم مألوف" وحفظه أثناء الإنشاء، يمكنك تضمينه اختياريًا في العرض.

إدارة المفاتيح

1. يمكن استخدام نقطة نهاية واجهة برمجة التطبيقات ListAndroidPackageKeys لاسترجاع جميع المفاتيح المرتبطة باسم حزمة، ما يوفّر للمطوّرين نظرة عامة منظَّمة (مثل جدول أو قائمة) لمراقبة حالة التسجيل.
2. اعرض certificateFingerprintSha256 لكل مفتاح إلى جانب حالة تسجيله (DRAFT أو OWNERSHIP_VERIFIED أو IN_REVIEW أو REGISTERED_ACTIVE أو PENDING_TRANSFER)، واستخدِم مؤشرات مرئية مميزة للتفريق بين الحالات.

1. يمكنك السماح للمطوّرين بتسجيل مفاتيح إضافية ضمن اسم حزمة حالي من خلال التكامل مع طريقة واجهة برمجة التطبيقات CreateAndroidPackageKey.

تسجيل اسم حزمة

1. استخدِم تنسيقًا مستندًا إلى النماذج حيث يُدخل المطوّرون اسم الحزمة في حقل نصي، بشرط ألا يكون تطبيقك قد جمع هذه المعلومات من قبل (على سبيل المثال، من خلال طلب سابق).
2. يمكنك استدعاء طريقة واجهة برمجة التطبيقات CreateAndroidPackage لتسجيل اسم حزمة ضمن حساب المطوّر، واستدعاء طريقة واجهة برمجة التطبيقات GetAndroidPackageRegistrationPolicy لتحديد قواعد أهلية المفاتيح السارية.
3. استنادًا إلى keySelectionStrategy المحدَّد لاسم الحزمة، اطلب من المطوّر تنفيذ أحد الإجراءات التالية:
   • إذا تم ضبط keySelectionStrategy على SELECT_KEY_FROM_LIST: اطلب من المطوّر اختيار مفتاح للتسجيل من قائمة knownKeys المقدَّمة (التي تحتوي على الملفات المرجعية لشهادات SHA-256)، مثل استخدام أزرار الاختيار. تتطلّب هذه العملية إثبات ملكية المفتاح (يُرجى الرجوع إلى قسم إثبات ملكية المفتاح أدناه).
   • إذا تم ضبط keySelectionStrategy على USE_ANY_KEY: اطلب من المطوّر تقديم مفتاح مباشرةً. لا حاجة إلى التحقّق من ملكية المفتاح في هذه الحالة.
4. اطلب طريقة واجهة برمجة التطبيقات CreateAndroidPackageKey لربط المفتاح الذي تم اختياره باسم الحزمة الجديد.

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

إثبات ملكية مفتاح

عند ضبط keySelectionStrategy على SELECT_KEY_FROM_LIST، على المطوّرين إثبات ملكية مفتاح التوقيع الخاص بهم. يتطلّب إثبات الملكية إرسال حزمة APK موقَّعة تتضمّن verificationToken الذي تم إنشاؤه من خلال واجهة برمجة التطبيقات.

لإتاحة التحقّق من ملكية المفتاح، ادمج طريقة واجهة برمجة التطبيقات VerifyAndroidPackageKeyOwnership وأنشئ مكوّنات واجهة المستخدم التالية:

• مكوّن عرض الرمز المميّز: اعرض verificationToken بشكل بارز داخل مقتطف الرمز، بما في ذلك زر "النسخ إلى الحافظة" المفيد.
• تعليمات إعداد المطوّر: توفّر تعليمات مفصّلة توجّه المطوّر إلى وضع ملف adi-registration.properties يحتوي على verificationToken في مجلد مواد عرض التطبيق.
• منطقة إفلات لإرسال حزمة APK: يمكنك توفير منطقة إفلات مخصّصة لتحميل الملفات من أجل تلقّي حزمة APK الموقَّعة.

توضيح سبب تسجيل مفتاح

عندما يتم ضبط الحقل justificationRequired لمفتاح معروف على REQUIRED، يتطلّب تسجيل هذا المفتاح مع اسم الحزمة من المطوّرين تقديم مبرّر تجاري شامل.

أرسِل هذا التبرير من خلال استدعاء طريقة JustifyAndroidPackageKeyRegistration في واجهة برمجة التطبيقات. تأكَّد من أنّ واجهة المستخدم في تطبيقك تتضمّن مساحة مخصّصة لإدخال النص لجمع السبب من المطوّر، وإعلامه بأنّ تقديم سبب منطقي مطلوب قبل إرسال طلب تسجيل المفتاح. تراجع Google السبب المُرسَل، وقد تستغرق هذه العملية ما يصل إلى 24 ساعة للموافقة عليه قبل اكتمال تسجيل اسم الحزمة.

أتمتة عملية التحقّق من المفاتيح المُدارة

إذا كان تطبيقك يدير مفتاح توقيع المطوّر، لن يتمكّن المطوّر من توقيع حزمة APK يدويًا لإثبات الملكية. بدلاً من ذلك، عليك تنفيذ طلب بيانات من واجهة برمجة التطبيقات VerifyAndroidPackageKeyOwnership تلقائيًا نيابةً عنهم.

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

اتّباع إرشادات العلامة التجارية

للحفاظ على ثقة المستخدمين وضمان الشفافية، يجب أن تلتزم جميع التطبيقات التي تتكامل مع واجهة برمجة التطبيقات Android Developer Console بإرشادات العلامة التجارية التالية.

المصطلحات والأحرف الكبيرة

عند الإشارة إلى المنتج في المواد أو المستندات الموجّهة للمستخدمين، يجب دائمًا استخدام الاسم الكامل Android Developer Console. لا تستخدِم الاختصار "ADC".

يجب الإشارة إلى البرنامج باسم "التحقّق من هوية مطوّر تطبيقات Android". يُرجى اتّباع هذه الطريقة في الكتابة واستخدام الأحرف الكبيرة في جميع السياقات.

لتجنُّب الالتباس مع ملفات APK أو حِزمات AAB، استخدِم مصطلح "اسم الحزمة" تحديدًا بدلاً من "الحزمة" فقط.

عند وصف عملية إضافة اسم حزمة، استخدِم عبارة "تسجيل اسم حزمة" بدلاً من "المطالبة باسم حزمة".

استخدام عبارة الحث على اتخاذ إجراء "تسجيل الدخول"

تعتمد مصادقة OAuth 2.0 في Android Developer Console على "خدمات الهوية من Google". لضمان الالتزام بإرشادات بناء هوية العلامة التجارية في Google Identity Services، يجب استخدام عبارة الحث على اتخاذ إجراء "المتابعة باستخدام حساب Google" أو "تسجيل الدخول باستخدام حساب Google" على زر التفويض. هذا النص إلزامي ولا يمكن تعديله، لأنه يضمن فهم المستخدمين أنهم يستخدمون بيانات اعتماد Google الخاصة بهم للسماح لتطبيقك بالوصول إلى حساب Google الخاص بهم.

الحفاظ على هوية العلامة التجارية ونزاهتها

عند دمج شعار Android Developer Console في واجهة تطبيقك، يجب اتّباع هذه المواصفات للحفاظ على الهوية البصرية وسلامة العلامة التجارية:

• موضع الشعار والتسلسل الهرمي: يجب استخدام شعار Android Developer Console الرسمي والمعتمَد فقط. يجب أن يظل الشعار دائمًا ثانويًا بالنسبة إلى عناصر العلامة التجارية الأساسية لتطبيقك لتجنُّب تقديم التطبيق بشكل مضلِّل على أنّه منتج رسمي من Google.

• النمط المرئي والتشوهات: يجب دائمًا عرض مادة العرض مع تقييد نسبة العرض إلى الارتفاع بالكامل. يجب عدم تشويه مكوّنات الشعار أو تمديدها أو إمالتها أو اقتصاصها أو قلبها أو تعديلها. لا تغيّر تشكيلة الألوان الرسمية أو تبدّل ألوان المقدّمة أو الخلفية أو تطبّق تظليل القطرات أو تأثيرات التوهّج أو التدرّجات الزخرفية.
• قيود الاستخدام: يجب عدم دمج أي عناصر هوية علامة تجارية تملكها Google في مواد عرض تطبيقك. لا يجوز استخدام شعار Android Developer Console إلا في سياق تصميم التطبيق للإشارة صراحةً إلى عملية دمج نشطة.

مراجع إضافية

• مرجع واجهة برمجة التطبيقات في Android Developer Console
• التحقّق من حالة تسجيل التطبيق باستخدام واجهة Android Developer ID Status API
• التسجيل في Android Developer Console
• التسجيل في Google Play Console
• توقيع تطبيقك