بدء استخدام خدمات ألعاب Play لـ C++

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

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

  • التفويض
  • الإنجازات
  • لوحة الصدارة
  • الأحداث
  • الألعاب المحفوظة
  • اتصالات الأجهزة المجاورة (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. يمكنك استخدام صفوف "المدير" لإدارة كائن 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 والمدير على عمليات تنفيذ غير آمنة وخيوط سلسلة المحادثات. ويمكن استدعاؤها على أي سلسلة محادثات بدون قفل خارجي، وسيتم تنفيذها بترتيب يتوافق مع طلب الاستدعاء.

تتوفر طرق الموصّل (تلك التي تقرأ الحالة) في شكلين رئيسيين. يقدم النوع الأول من الطريقة (بأسماء مثل 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) في خدمات ألعاب Google Play للحصول على مزيد من التفاصيل، واطّلِع على النماذج التي توضح كيفية استخدام حزمة تطوير البرامج (SDK).

إذا كانت لعبتك تستخدم خادم خلفية، فراجع تمكين الوصول من جانب الخادم إلى خدمات ألعاب Google Play.