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

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

توفّر حزمة تطوير البرامج (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 الخاصة بك كذلك، ولن تحتاج إلى إعادة تهيئته عند إيقاف تطبيق Android Activity مؤقتًا ثم استئنافه.

   // 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);});

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

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

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

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

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

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