"خدمات ألعاب Play" لبرنامج C++

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

توفّر حزمة تطوير البرامج (SDK) الخاصة بلغة C++ في "خدمات ألعاب Google Play" واجهة برمجة تطبيقات بلغة C++ لاستخدامها مع "خدمات ألعاب Google Play"، وهي مخصّصة للمطوّرين الذين لديهم تنفيذ حالي للعبة بلغة C++.

تنفّذ حزمة تطوير البرامج (SDK) حاليًا الخدمات التالية:

• التفويض
• الإنجازات
• لوحات الصدارة
• الفعاليات
• حفظ التقدم في الألعاب
• Nearby Connections (على أجهزة Android فقط)
• إحصاءات اللاعب

المفاهيم

بشكل عام، يمكنك استخدام حزمة تطوير البرامج (SDK) باتّباع الخطوات التالية:

1. إعداد ضبط النظام الأساسي على Android
2. استخدِم GameServices::Builder لإعداد وإنشاء عنصر GameServices. يحاول العنصر GameServices تلقائيًا تسجيل الدخول، ويعرض النتيجة من خلال معاودة الاتصال OnAuthActionFinished(). دوِّن النتيجة التي تعرضها دالة معاودة الاتصال. إذا تعذّر تسجيل الدخول تلقائيًا، يمكنك عرض زر للسماح للمستخدمين بتسجيل الدخول.

3. بعد تلقّي النتيجة OnAuthActionFinished()، يمكنك استخدام العنصر GameServices وعناصر الإدارة الفرعية الخاصة به لإجراء طلبات إلى "خدمات ألعاب Play"، بما في ذلك:

   • تسجيل الدخول (بعد تعذُّر التفويض): StartAuthorizationUI()
   • فتح قفل الإنجازات: Achievements().Unlock()
   • عرض الإنجازات باستخدام واجهة المستخدم المضمّنة: Achievements().ShowAllUI()
   • إرسال نتيجة عالية: Leaderboards().SubmitScore()
   • تسجيل الخروج: SignOut()

4. عند الانتهاء من استخدام الكائن GameServices، أعِد ضبطه أو أتلِفه.

على مستوى أكثر تفصيلاً:

1. تهيئة إعدادات النظام الأساسي: هذا عنصر يحتوي على معلومات تهيئة خاصة بالنظام الأساسي. في نظام التشغيل Android، يحتوي إعداد النظام الأساسي على Java VM ومؤشر إلى Activity الحالي:

   // In android_main(), create a platform configuration
   // and bind the object activity.
   // Alternately, attach the activity in JNI_Onload().
   gpg::AndroidPlatformConfiguration platform_configuration;
   platform_configuration.SetActivity(state->activity->clazz);
   

2. إنشاء عنصر GameServices: هذا العنصر هو نقطة الدخول الرئيسية لوظائف "خدمات ألعاب Google Play". يتم إنشاء مثيلات GameServices باستخدام GameServices::Builder.

   في معظم عمليات التنفيذ، سيظل عنصر GameServices معيّن ثابتًا ما دام بيئة C الخاصة بك كذلك، ولن تحتاج إلى إعادة تهيئته عند إيقاف Activity Android مؤقتًا واستئنافه.

   // Creates a GameServices object that has lambda callbacks.
   game_services_ = gpg::GameServices::Builder()
           .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
           .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
               is_auth_in_progress_ = true;
               started_callback(op);
           })
           .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                        gpg::AuthStatus status) {
               LOGI("Sign in finished with a result of %d", status);
               is_auth_in_progress_ = false;
               finished_callback(op, status);
           })
           .Create(pc);
   

3. استخدِم فئات Manager لإدارة عنصر GameServices. يمكن الوصول إلى المدراء من مثيل GameServices، كما يتم تجميع الوظائف ذات الصلة بالمجموعة معًا. وتتضمّن الأمثلة على ذلك أدوات إدارة الإنجازات وقوائم الصدارة. ولا تحتوي على أي حالة مرئية للمستخدم. يتم عرض المدراء حسب المرجع، ويتحكّم مثيل GameServices الذي يحتوي على المدراء في دورة حياتهم. يجب ألا يحتفظ عميلك بمرجع "الحساب الإداري". بدلاً من ذلك، يجب أن يحتفظ عميلك بنسخة GameServices.

   تعرض أدوات المعالجة البيانات من خلال عناصر من نوع القيمة غير القابلة للتغيير. تعكس هذه القيم عرضًا متسقًا للبيانات الأساسية في الوقت الذي تم فيه تقديم طلب البحث.

   // Submit a high score
   game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
   
   // Show the default Achievements UI
   game_services_->Achievements().ShowAllUI();
   

4. عند الانتهاء من استخدام العنصر GameServices، يمكنك تنظيفه من خلال استدعاء reset() على unique_ptr الذي يملكه، أو من خلال السماح لـ unique_ptr بتدميره تلقائيًا عند الخروج من النطاق.

نموذج سلاسل المحادثات

ما لم يُذكر خلاف ذلك، تتضمّن جميع طرق GameServices وManager عمليات تنفيذ غير متزامنة وآمنة للاستخدام المتزامن. ويمكن استدعاؤها في أي سلسلة محادثات بدون قفل خارجي، وسيتم تنفيذها بترتيب يتوافق مع ترتيب استدعائها.

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

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

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

المعلومات الخاصة بالمنصّة

لبدء استخدام حزمة تطوير البرامج الخاصة بألعاب Play التي تستخدم لغة C++‎ على Android، انتقِل إلى دليل البدء السريع.

محتوى إضافي للقراءة

احرص على قراءة مستندات الفئة المضمّنة في حزمة C++ SDK الخاصة بـ "خدمات ألعاب Google Play" للحصول على مزيد من التفاصيل، واطّلِع على الأمثلة التي توضّح كيفية استخدام حزمة SDK.

إذا كانت لعبتك تستخدم خادمًا للواجهة الخلفية، اطّلِع على تفعيل إمكانية الوصول إلى "خدمات ألعاب Google Play" من جهة الخادم.