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

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

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

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

المفاهيم

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

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

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 تتحلى بعمليات تنفيذ غير متزامنة وآمنة من حيث مؤشرات الترابط. ويمكن استدعاؤها في أي سلسلة محادثات بدون قفل خارجي، وسيتم تنفيذها بترتيب متوافق مع ترتيب invocatio.

تتوفّر طريقتَا وصول رئيسيتان (تلك التي تقرأ الحالة). يقدّم النوع الأول من الأساليب (بأسماء مثل 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، انتقِل إلى دليل البدء السريع.

مراجع إضافية

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

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