"خدمات ألعاب Play" لبرنامج C++
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
بعد إيقاف واجهة برمجة التطبيقات
Google Sign-In API
نهائيًا، سنزيل حزمة تطوير البرامج (SDK) لألعاب الإصدار 1 في عام 2026. بعد شباط (فبراير) 2025، لن تتمكّن من نشر
العناوين التي تم دمجها حديثًا مع حزمة تطوير البرامج (SDK) لإصدار 1 من "ألعاب Google Play" على Google Play. ننصحك باستخدام
حزمة تطوير البرامج (SDK) لإصدار 2 من "ألعاب Google Play" بدلاً من ذلك.
على الرغم من أنّ العناوين الحالية التي تم دمجها مع الإصدار 1 من الألعاب السابقة ستظل تعمل لعدة
سنوات، ننصحك بنقل بياناتها إلى الإصدار 2
اعتبارًا من حزيران (يونيو) 2025.
يتناول هذا الدليل استخدام حزمة تطوير البرامج (SDK) لإصدار 1 من "خدمات ألعاب Play". لا تتوفّر حزمة C++ SDK لإصدار
"خدمات ألعاب Play" 2 حتى الآن.
توفّر حزمة تطوير البرامج (SDK) لـ C++ في "خدمات ألعاب Google Play" واجهة برمجة تطبيقات C++ لاستخدامها مع "خدمات ألعاب Google Play"، وهي مخصّصة للمطوّرين الذين لديهم عملية تنفيذ حالية لـ C++ في لعبتهم.
في الوقت الحالي، توفّر حزمة تطوير البرامج (SDK) الخدمات التالية:
- التفويض
- الإنجازات
- لوحات الصدارة
- الأحداث
- حفظ التقدم في الألعاب
- Nearby Connections (على أجهزة Android فقط)
- إحصاءات اللاعبين
المفاهيم
بشكل عام، يمكنك استخدام حزمة تطوير البرامج (SDK) باتّباع الخطوات التالية:
- إعداد إعدادات النظام الأساسي لنظام التشغيل Android
- استخدِم
GameServices::Builder لضبط عنصر GameServices
وإنشاءه. يحاول عنصر GameServices تسجيل الدخول تلقائيًا، ويعرض النتيجة من خلال دالة استدعاء OnAuthActionFinished(). يُرجى تدوين النتيجة
التي عرضتها الدالة callback. إذا تعذّر تسجيل الدخول تلقائيًا، يمكنك
عرض زر للسماح للمستخدمين بتسجيل الدخول.
بعد تلقّي النتيجة OnAuthActionFinished()، يمكنك استخدام GameServices وعناصر "المدراء" الفرعية لإجراء مكالمات إلى خدمات "ألعاب Play"، بما في ذلك:
- تسجيل الدخول (بعد تعذُّر التفويض):
StartAuthorizationUI()
- فتح قفل الإنجازات:
Achievements().Unlock()
- عرض الإنجازات باستخدام واجهة المستخدم المدمجة:
Achievements().ShowAllUI()
- أرسِل أعلى نتيجة:
Leaderboards().SubmitScore()
- تسجيل الخروج:
SignOut()
عند الانتهاء من استخدام عنصر GameServices، أعِد ضبطه أو أحذِفه.
على مستوى أكثر تفصيلاً:
بدء إعدادات المنصة: هذا عنصر يحتوي على
معلومات بدء خاصة بالمنصة. على نظام التشغيل 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);
إنشاء عنصر 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);
استخدِم فئات "المدير" لإدارة عنصر GameServices. يمكن الوصول إلى "المديرين" من مثيل GameServices والوظائف ذات الصلة بالمجموعات
معًا. ومن أمثلة هذه التطبيقات
مديرا الإنجاز وقائمة الصدارة. ولا تحتوي على حالة
مرئية للمستخدم. يتم عرض المدراء بالرجوع إلى مثيل
GameServices الذي يحتوي عليهم، والذي يتحكّم في دورة حياتهم. يجب ألا يحتفظ العميل أبدًا
بمرجع حساب مدير. بدلاً من ذلك، يجب أن يحتفظ العميل بمثيل
GameServices.
تعرض العناصر الإدارية البيانات من خلال عناصر نوع القيمة غير القابلة للتغيير. تعكس هذه القيم
عرضًا متّسقًا للبيانات الأساسية في النقطة الزمنية التي تم فيها
إجراء الطلب.
// Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();
عند الانتهاء من استخدام عنصر 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".
يخضع كل من المحتوى وعيّنات التعليمات البرمجية في هذه الصفحة للتراخيص الموضحّة في ترخيص استخدام المحتوى. إنّ Java وOpenJDK هما علامتان تجاريتان مسجَّلتان لشركة Oracle و/أو الشركات التابعة لها.
تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-07-26 (حسب التوقيت العالمي المتفَّق عليه)"],[],[],null,["# Play Games Services for C++\n\nFollowing the deprecation of the\n[Google Sign-In](https://android-developers.googleblog.com/2024/09/streamlining-android-authentication-credential-manager-replaces-legacy-apis.html)\nAPI, we are removing the games v1 SDK in 2026. After February 2025, you will be unable to publish\ntitles that are newly integrated with games v1 SDK, on Google Play. We recommend that you use the\ngames v2 SDK instead. \n\nWhile existing titles with the previous games v1 integrations continue to function for a\ncouple of years, you are encouraged to\n[migrate to v2](/games/pgs/android/migrate-to-v2)\nstarting June 2025. \n\nThis guide is for using the Play Games Services v1 SDK. The C++ SDK for\nPlay Games Services v2 is not yet available.\n\nThe Google Play games Services C++ SDK provides a C++ API for use with Google Play Game\nservices, and is meant for developers who have an existing C++ implementation\nof their game.\n\nCurrently, the SDK implements the following services:\n\n- Authorization\n- Achievements\n- Leaderboards\n- Events\n- Saved Games\n- Nearby Connections (Android only)\n- Player Statistics\n\nConcepts\n--------\n\nAt a high level, you use the SDK by following these steps:\n\n1. Set up a platform configuration for Android.\n2. Use a `GameServices::Builder` to configure and construct a `GameServices` object. The `GameServices` object automatically attempts to sign in, and returns the result via an `OnAuthActionFinished()` callback. Take note of the result returned by the callback. If the automatic sign-in attempt failed, you can display a button to let users sign in.\n3. After receiving the `OnAuthActionFinished()` result, you can use the\n `GameServices` object and its child Managers to make Play Games services calls,\n including:\n\n - Sign in (after authorization fails): `StartAuthorizationUI()`\n - Unlock achievements: `Achievements().Unlock()`\n - Show achievements using built-in UI: `Achievements().ShowAllUI()`\n - Submit a high score: `Leaderboards().SubmitScore()`\n - Sign out: `SignOut()`\n4. When you are done using the `GameServices` object, reset or destroy it.\n\nAt a more detailed level:\n\n1. Initialize a platform configuration: This is an object that contains\n platform-specific initialization information. On Android, the platform configuration contains the\n Java VM and a pointer to the current `Activity`:\n\n // In android_main(), create a platform configuration\n // and bind the object activity.\n // Alternately, attach the activity in JNI_Onload().\n gpg::AndroidPlatformConfiguration platform_configuration;\n platform_configuration.SetActivity(state-\u003eactivity-\u003eclazz);\n\n2. Construct a `GameServices` object: This object is the main entry point for\n Google Play games Services functionality. `GameServices` instances are created\n with `GameServices::Builder`.\n\n In most implementations, a given `GameServices` object will persist as long as\n your C environment does; you do not need to reinitialize it when your\n Android `Activity` pauses and resumes. \n\n // Creates a GameServices object that has lambda callbacks.\n game_services_ = gpg::GameServices::Builder()\n .SetDefaultOnLog(gpg::LogLevel::VERBOSE)\n .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {\n is_auth_in_progress_ = true;\n started_callback(op);\n })\n .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,\n gpg::AuthStatus status) {\n LOGI(\"Sign in finished with a result of %d\", status);\n is_auth_in_progress_ = false;\n finished_callback(op, status);\n })\n .Create(pc);\n\n3. Use the Manager classes to manage your `GameServices` object. Managers are accessed from a `GameServices` instance and group related functionality\n together. Examples of these\n include the Achievement and Leaderboard Managers. They contain no user-visible\n state themselves. Managers are returned by reference, and the containing\n `GameServices` instance controls their lifecycle. Your client should never hold\n onto a Manager reference. Instead, your client should hold on to the\n `GameServices` instance.\n\n Managers return data via immutable value type objects. These values\n reflect a consistent view of the underlying data at the point in time when\n the query was made. \n\n // Submit a high score\n game_services_-\u003eLeaderboards().SubmitScore(leaderboard_id, score);\n\n // Show the default Achievements UI\n game_services_-\u003eAchievements().ShowAllUI();\n\n4. When you are finished using the `GameServices` object, clean up by\n calling `reset()` on the `unique_ptr` that owns it, or by letting the\n `unique_ptr` automatically destroy it when going out of scope.\n\nThreading model\n---------------\n\nUnless otherwise noted, all `GameServices` and Manager methods have\nthread-safe, asynchronous implementations. They can be called on any thread without\nexternal locking, and will execute in an order consistent with their invocation\norder.\n\nAccessor methods (those that read state) come in two major variants. The first\ntype of method (with names like `FetchProperty()`) asynchronously supplies its results\nto a provided callback; the second (with names like\n`FetchPropertyBlocking()`) synchronously returns its results to the calling\nthread. \n\n // Blocking callback\n gpg::AchievementManager::FetchAllResponse fetchResponse =\n game_services_-\u003eAchievements().FetchAllBlocking(std::chrono::milliseconds(1000));\n\n // Non-blocking callback\n game_services_-\u003eAchievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,\n [] (gpg::AchievementManager::FetchAllResponse response) {\n LogI(\"Achievement response status: %d\", response.status);});\n\nAll user callbacks are invoked on a dedicated callback thread. This thread is\npotentially distinct from any platform concept of a \"main thread\" or \"UI\nthread\". You should also try to ensure that user callbacks execute quickly; a stalled callback thread\nmay cause user-visible issues (for example, delayed completion of a sign-out\nrequest).\n\nPlatform-specific information\n-----------------------------\n\nTo get started using the Play Games C++ SDK on Android, continue to the\n[quickstart guide](/games/pgs/v1/cpp/quickstart).\n\nFurther reading\n---------------\n\nBe sure to read the class documentation that comes in the Google Play Game\nservices C++ SDK for further details, and check out the\n[samples](https://github.com/playgameservices/) that demonstrate how to use the SDK.\n\nIf your game uses a backend server, see\n[Enabling Server-Side Access to Google Play Games Services](/games/pgs/v1/android/server-access)."]]
