بدء استخدام "خدمات ألعاب Play" لـ C++ على نظام Android

بعد إيقاف واجهة برمجة التطبيقات تسجيل الدخول باستخدام Google نهائيًا، سنزيل الإصدار v1 من حزمة تطوير البرامج (SDK) للألعاب في عام 2026. بعد فبراير 2025، لن يكون بإمكانك نشر الألعاب التي تم دمجها حديثًا مع الإصدار v1 من حزمة SDK للألعاب على Google Play. ننصحك باستخدام الإصدار v2 من حزمة SDK للألعاب بدلاً من ذلك.
مع أنّ التطبيقات الحالية التي تتضمّن عمليات الدمج السابقة للإصدار 1 من "خدمات ألعاب Google Play" ستستمر في العمل لعدّة سنوات، ننصحك بنقل البيانات إلى الإصدار 2 بدءًا من يونيو 2025.
هذا الدليل مخصّص لاستخدام الإصدار 1 من حزمة تطوير البرامج (SDK) الخاصة بـ "خدمات ألعاب Play". حزمة تطوير البرامج (SDK) للغة C++ الخاصة بالإصدار 2 من "خدمات ألعاب Play" غير متاحة بعد.

سيوضّح لك دليل المطوّرين هذا كيفية تجميع لعبة C++‎ وتشغيلها على Android باستخدام واجهة برمجة التطبيقات لخدمات ألعاب Google Play. قبل البدء، نزِّل المتطلبات التالية واضبطها:

• ‫Android NDK، الإصدار 14 أو الإصدارات الأحدث
• الإصدار 10 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لنظام التشغيل Android وأحدث إصدار من حزمة أدوات تطوير Android (ADT) في Eclipse
• يجب أن يعمل الجهاز بالإصدار 4.0 من نظام التشغيل Android (المستوى 14 لواجهة برمجة التطبيقات) أو إصدار أحدث.
• أحدث إصدار من حزمة تطوير البرامج (SDK) الخاصة بخدمات Google Play

يستخدم دليل المطوّرين هذا "حزمة تطوير البرامج الأصلية لنظام التشغيل Android" (NDK). إذا لم تكن معتادًا على NDK، راجِع مستندات NDK وأمثلتها قبل المتابعة.

الخطوة 1: إعداد بيئتك

1. نزِّل حزمة تطوير البرامج (SDK) لنظام التشغيل Android وAndroid NDK واستخرِجهما إلى جهازك. في بيئتك، اضبط SDK_ROOT على موقع مجلد حزمة تطوير البرامج (SDK) لنظام التشغيل Android، واضبط NDK_ROOT على موقع مجلد Android NDK.
2. نزِّل ألعابًا نموذجية بلغة C++‎. يشير دليل المطوّرين هذا إلى موقع العيّنات على جهازك باسم SAMPLES_DIR.
3. نزِّل حزمة تطوير البرامج (SDK) الخاصة "بخدمات ألعاب Google Play" التي تستخدم لغة C++‎. استخرِج حزمة تطوير البرامج (SDK) على جهاز التطوير. في بيئتك، اضبط المتغيّر NDK_MODULE_PATH ليشير إلى الدليل أعلى الدليل gpg-cpp-sdk. يجب أن تكون بنية الدليل على النحو التالي:

   NDK_MODULE_PATH/
   gpg-cpp-sdk/

4. افتح Eclipse. إذا لم يسبق لك إجراء ذلك، عليك إخبار Eclipse بمكان تثبيت NDK من خلال النقر على Preferences > Android > NDK.

5. استورِد مشروع مكتبة "خدمات Google Play" إلى مساحة عمل Eclipse.

   1. في Eclipse، انقر على ملف (File) > استيراد (Import) > Android > استيراد رمز Android حالي إلى مساحة العمل (Existing Android Code into Workspace).
   2. اختَر SDK_ROOT/extras/google/google_play_services/libproject/google-play-services_lib حيث SDK_ROOT هو الموقع الجغرافي لحزمة تطوير البرامج (SDK) لنظام التشغيل Android.
   3. انقر على إنهاء.

6. استورِد نموذج المشروع البسيط إلى مساحة عمل Eclipse.

   1. في Eclipse، انقر على ملف (File) > استيراد (Import) > Android > استيراد رمز Android حالي إلى مساحة العمل (Existing Android Code into Workspace).
   2. اختَر SAMPLES_DIR/samples-android/minimalist.
   3. انقر على إنهاء.

7. انقر بزر الماوس الأيمن على مشروع MinimalistActivity وانقر على الخصائص (Properties). ضمن Android، انتقِل إلى قسم المكتبة وتأكَّد من أنّ مشروع google-play-services_lib تمت الإشارة إليه بشكل صحيح. إذا لم يكن كذلك، أزِل المرجع وأضِفه مرة أخرى من مساحة عملك.

سيقوم Eclipse تلقائيًا بتجميع مصادر Java وAndroid الخاصة بمشروعك، ولكن يجب تجميع الرمز البرمجي الأصلي في المجلد jni بشكل منفصل. لتنفيذ ذلك يدويًا، انتقِل إلى المجلد jni وشغِّل ndk-build. يُرجى تذكُّر إجراء ذلك بعد إجراء أي تغييرات داخل المجلد jni.

من المفترض أن يتم تجميع مشروعك الآن، ولكن لن يعمل بعد. عليك أولاً إعداد لعبتك في Google Play Console.

الخطوة 2: إعداد اللعبة في Google Play Console

أنشئ إدخالاً للعبتك في Google Play Console. يؤدي ذلك إلى تفعيل "خدمات الألعاب" لتطبيقك وإنشاء معرّف عميل OAuth 2.0 إذا لم يكن لديك معرّف حاليًا.

1. أنشئ إدخالاً للعبتك باتّباع الخطوات الموضّحة في مقالة إعداد "خدمات ألعاب Google Play".
2. في AndroidManifest.xml، غيِّر السمة package الخاصة بالعلامة <manifest> إلى اسم الحزمة الذي اخترته عند إعداد Google Play Console. قد تحتاج إلى إصلاح بعض المراجع في جميع أنحاء المشروع بعد إجراء هذا التغيير (خاصةً المراجع إلى فئة R التي تم إنشاؤها).
3. افتح res/values/ids.xml وأدخِل رقم تعريف التطبيق. يُرجى العِلم أنّ رقم تعريف التطبيق ليس هو رقم تعريف العميل، بل هو الرقم بجانب اسم لعبتك في صفحة تفاصيل اللعبة ضمن Google Play Console.

الخطوة 3: تشغيل العيّنة

لتشغيل النموذج، يجب أن يكون لديك جهاز Android حقيقي أو محاكي مثبَّت عليه "خدمات Google Play":

1. نفِّذ ndk-build لتجميع الرمز البرمجي الأصلي.
2. في Eclipse، انقر على تشغيل > التشغيل كـ > تطبيق Android وشغِّل النموذج على جهازك.
3. عند فتح العيّنة، انقر على أي مكان على الشاشة. من المفترض أن يظهر لك شعار "ألعاب Google Play". إذا تم إعداد تطبيقك بشكل صحيح، سيُطلب منك تسجيل الدخول.

ملاحظة مهمة: احرص على توقيع حزمة APK باستخدام الشهادة نفسها التي تم ضبط بصمتها على Google Play Console. سيؤدي عدم الالتزام بذلك إلى حدوث أخطاء.

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

اختياري: الإنشاء تلقائيًا باستخدام Eclipse

توضّح لك الخطوات التالية كيفية ضبط Eclipse لتشغيل ndk-build تلقائيًا عند إجراء تغييرات على الملفات في المجلد jni.

1. انقر بزر الماوس الأيمن على مشروع MinimalistActivity، ثم انقر على الخصائص (Properties). في نافذة "السمات" (Properties)، اختَر لوحة أدوات الإنشاء (Builders).
2. انقر على جديد لإضافة أداة إنشاء جديدة، ثمّ اختَر برنامج وانقر على حسنًا.
3. في حقل الاسم، أدخِل NDK Builder.
4. ضمن الموقع الجغرافي، انقر على تصفُّح نظام الملفات وانتقِل إلى دليل NDK_ROOT واختَر الأمر ndk-build.
5. ضمن دليل العمل، انقر على تصفّح مساحة العمل واختَر مجلد مشروع MinimalistActivity.
6. انقر على علامة التبويب إعادة تحميل. تأكَّد من وضع علامة في المربّع إعادة تحميل الموارد عند الانتهاء.
7. انقر على زر الاختيار موارد محدّدة، ثم انقر على تحديد الموارد. في مربّع الحوار الناتج، اختَر المجلد jni ضمن MinimalActivity.
8. انقر على تطبيق ثم على حسنًا لإنهاء عملية إنشاء "أداة الإنشاء".

الآن، في كل مرة تعدّل فيها ملفًا ضمن المجلد jni، سيشغّل Eclipse الأمر ndk-build ويطبع الناتج في Eclipse Console.

ملاحظة: إذا ظهرت لك أخطاء عند تعديل ملفات C أو C++ في Eclipse تمنعك من إنشاء المشروع، يمكنك إيقاف ميزة الإبلاغ عن أخطاء C/C++ في Eclipse. في خصائص مشروعك، انتقِل إلى C/C++ General > Code Analysis > Launching وتأكَّد من إلغاء تحديد المربّعين. بعد ذلك، انقر على تطبيق وموافق. هذا حلّ بديل لمنع Eclipse من التحقّق من الرمز البرمجي الأصلي، ولكنّه لا يحلّ أي أخطاء أساسية قد تحدث.