تسجيل أسماء الحِزم باستخدام واجهة برمجة التطبيقات 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. في قائمة التنقّل (☰)، انقر على واجهات برمجة التطبيقات والخدمات > المكتبة.
3. اختَر مشروع Google Cloud الذي تريد تفعيل واجهة برمجة التطبيقات فيه من القائمة المنسدلة للمشروع.
4. استخدِم شريط البحث واجهات برمجة التطبيقات والخدمات لاختيار Android Developer Console API.
5. فعِّل واجهة برمجة التطبيقات:
   1. انتقِل إلى صفحة النظرة العامة على واجهة برمجة التطبيقات عن طريق اختيارها من نتائج البحث.
   2. انقر على الزر الأزرق تفعيل. تفعِّل Google Cloud واجهة برمجة التطبيقات للمشروع الذي اخترته، ولا يستغرق ذلك عادةً سوى لحظة. بعد تفعيلها، يمكنك البدء في استخدامها.

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

لإجراء طلبات إلى Android Developer Console API، يجب مصادقة طلباتك باستخدام 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 API، يجب أن تستخدم التطبيقات مسار خادم الويب في 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 ضِمن [اسم التطبيق]"
• زر الإجراء: الزر "متابعة باستخدام 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 API بإرشادات العلامة التجارية التالية.

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

عند الإشارة إلى المنتج في المواد أو المستندات المخصّصة للمستخدمين، استخدِم دائمًا الاسم الكامل 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 ID Status API
• التسجيل في Android Developer Console
• التسجيل في Google Play Console
• توقيع تطبيقك