إعداد "ألعاب Google Play" لـ Unity والمصادقة

يوضّح لك هذا المستند كيفية إعداد مشروع Unity لاستخدام المكوّن الإضافي "خدمات ألعاب Google Play" لمحرّك Unity. ستتعرّف على كيفية تثبيت المكوّن الإضافي وإعداد مشروع Unity. يتناول المستند أيضًا كيفية التحقّق من صحة خدمة المصادقة.

قبل البدء

راجِع متطلبات البرامج. إعداد Play Console وتثبيت Unity Editor

تثبيت المكوّن الإضافي

لتنزيل المكوّن الإضافي لـ "ألعاب Google Play" وتثبيته في Unity، اتّبِع الخطوات التالية في Unity Editor:

  1. نزِّل مستودع GitHub.

  2. في الدليل current-build، ابحث عن الملف unitypackage. يمثّل هذا الملف المكوّن الإضافي. على سبيل المثال، يجب أن يكون مشابهاً لما يلي:

      current-build/GooglePlayGamesPluginForUnity-X.YY.ZZ.unitypackage

إعداد مشروع Unity

لإعداد مشروع Unity في إعدادات المشغّل، اتّبِع الخطوات التالية:

  1. افتح مشروع لعبتك.

  2. في Unity Editor، انقر على مواد العرض (Assets) > استيراد حزمة (Import Package) > حزمة مخصّصة (Custom Package) لاستيراد ملف unitypackage إلى مواد عرض مشروعك.

  3. تأكَّد من ضبط النظام الأساسي الحالي للإنشاء على Android.

    1. في القائمة الرئيسية، انقر على ملف (File) > إعدادات الإنشاء (Build Settings).

    2. اختَر Android وانقر على تبديل النظام الأساسي.

    3. يجب أن يظهر عنصر قائمة جديد ضمن نافذة > ألعاب Google Play. إذا لم يكن كذلك، أعِد تحميل مواد العرض بالنقر على مواد العرض > إعادة التحميل، ثم حاوِل ضبط منصة الإصدار مرة أخرى.

  4. في Unity Editor، انقر على ملف (File) > إعدادات الإنشاء (Build Settings) > إعدادات المشغّل (Player Settings) > إعدادات أخرى (Other Settings).

  5. في مربّع مستوى واجهة برمجة التطبيقات المستهدَف، اختَر إصدارًا.

  6. في مربّع نظام البرمجة الخلفية، أدخِل IL2CPP.

  7. في المربّع البُنى المستهدَفة، اختَر قيمة.

  8. دوِّن اسم الحزمة package_name.يمكنك استخدام هذه المعلومات لاحقًا.

إعدادات المشغّل في مشروع Unity
إعدادات اللاعب في مشروع Unity

إنشاء ملف تخزين مفاتيح جديد

لإثبات صحة بيانات الاعتماد، تحتاج إلى مفتاح. اتّبِع الخطوات التالية:

  1. في Unity Editor، انقر على ملف (File) > إعدادات الإنشاء (Build settings) > إعدادات المشغّل (Player settings).
  2. في قسم إعدادات النشر، انقر على أداة إدارة ملفات تخزين المفاتيح.
    1. في نافذة إدارة ملفات تخزين المفاتيح، انقر على ملف تخزين المفاتيح > إنشاء جديد > في أي مكان.
    2. اختَر مجلدًا وقدِّم اسمًا لملف تخزين المفاتيح.
    3. في مربّع كلمة المرور، أدخِل كلمة مرور وأكِّدها.
    4. انقر على إضافة مفتاح.

دوِّن اسم المجلد. يمكنك استخدام هذا الاسم من أجل إنشاء بيانات اعتماد في Google Cloud.

نسخ موارد Android من Play Console

يتضمّن كل إنجاز ولوحة صدارة وحدث تنشئه في Play Console أحد موارد Android التي تستخدمها عند إعداد مشروع Unity.

للحصول على موارد Android الخاصة بلعبتك، اتّبِع الخطوات التالية:

  1. في Google Play Console، افتح اللعبة.

  2. في صفحة الإعدادات ضمن "خدمات ألعاب Play" (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > الإعدادات)، انقر على الحصول على مراجع.

  3. في نافذة الموارد، انقر على علامة التبويب Android(XML).

  4. اختَر محتوى مراجع Android (AndroidManifest.xml) وانسَخه.

إضافة موارد Android إلى مشروع Unity

أضِف موارد Android التالية إلى مشروع Unity:

  1. في Unity Editor، انقر على Window > ألعاب Google Play > Setup > إعداد Android.

    • في حقل الدليل لحفظ الثوابت، أدخِل اسم المجلد الذي سيتم حفظ ملف الثوابت فيه.

    • في حقل اسم فئة الثوابت، أدخِل اسم فئة C# التي تريد إنشاءها، بما في ذلك مساحة الاسم.

      على سبيل المثال، إذا كان صف C# هو id.cs وموجودًا ضمن Assets > myproject > scripts > id.cs. يمكن أن يكون اسم فئة الثوابت myproject.scripts.id.

    • في حقل تعريف الموارد، الصِق بيانات موارد Android (ملف AndroidManifest.xml) التي نسختها من Google Play Console.

    • اختياري: في حقل معرّف العميل، أدخِل معرّف العميل لتطبيق الويب المرتبط.

      للحصول على معرّف العميل الخاص بلعبتك من Google Cloud، اطّلِع على إنشاء معرّفات العملاء.

      لا تحتاج إلى ذلك إلا إذا كان لديك خادم خلفية مستند إلى الويب للعبتك وكنت بحاجة إلى رمز مصادقة الخادم لاستبداله برمز مميّز للوصول من خلال خادم الخلفية، أو إذا كنت بحاجة إلى رمز مميّز للمعرّف كي يتمكّن اللاعب من إجراء طلبات أخرى من واجهات برمجة التطبيقات غير المتعلّقة باللعبة.

    • انقر على إعداد. يؤدي ذلك إلى ضبط لعبتك باستخدام رقم تعريف العميل وإنشاء فئة C# تحتوي على ثوابت لكل مورد من موارد Android.

  2. في Unity Editor، انقر على Window > ألعاب Google Play > Setup > Nearby Connections Setup.

    • في حقل معرّف خدمة الاتصال المباشر، أدخِل package_name.

      استخدِم package_name نفسه الذي استخدمته في إعداد مشروع Unity.

    • انقر على إعداد.

اختيار منصة اجتماعية

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

يمكن الوصول إلى طلبات البيانات من واجهة برمجة التطبيقات العادية من خلال العنصر Social.Active، وهو مرجع إلى واجهة ISocialPlatform. يمكن الوصول إلى الإضافات غير العادية في "خدمات ألعاب Google Play" من خلال تحويل نوع الكائن Social.Active إلى فئة PlayGamesPlatform، حيث تتوفّر الطرق الإضافية.

استخدام المكوّن الإضافي بدون إلغاء المنصة التلقائية على وسائل التواصل الاجتماعي

عند طلب PlayGamesPlatform.Activate، تصبح "خدمات ألعاب Google Play" هي المنصة الاجتماعية التلقائية التي يتم تنفيذها. وهذا يعني أنّ إضافة "خدمات ألعاب Google Play" تنفّذ طلبات ثابتة للطُرق في Social وSocial.Active، وهو السلوك المتوقّع لمعظم الألعاب التي تستخدم الإضافة.

ومع ذلك، إذا أردت لأي سبب إبقاء التنفيذ التلقائي متاحًا (على سبيل المثال، لاستخدامه في إرسال الإنجازات وقوائم الصدارة إلى منصة تواصل اجتماعي مختلفة)، يمكنك استخدام مكوّن خدمات ألعاب Google Play الإضافي بدون إلغاء المكوّن التلقائي. ولإجراء ذلك:

  1. استدعِ طريقة PlayGamesPlatform.Activate.
  2. إذا كان Xyz هو اسم طريقة تستدعيها في الفئة Social، لا تستدعِ Social.Xyz. بدلاً من ذلك، اتّصِل بالرقم PlayGamesPlatform.Instance.Xyz.
  3. استخدِم السمة PlayGamesPlatform.Instance بدلاً من Social.Active عند التفاعل مع "خدمات ألعاب Google Play".

بهذه الطريقة، يمكنك حتى إرسال النتائج والإنجازات في الوقت نفسه إلى منصتَين أو أكثر من منصات التواصل الاجتماعي:

    // Submit achievement to original default social platform
    Social.ReportProgress("MyAchievementIdHere", 100.0f, callback);

    // Submit achievement to Google Play
    PlayGamesPlatform.Instance.ReportProgress("MyGooglePlayAchievementIdHere", 100.0f, callback);

التحقّق من خدمة المصادقة

تتم محاولة الاتصال بخدمات "ألعاب Play" تلقائيًا باستخدام مصادقة المنصّة عند فتح لعبتك. في حال نجاح عملية الربط، ستعرض لعبتك طلبًا لتسجيل الدخول وستكون جاهزة لاستخدام إضافة "خدمات ألعاب Google Play" في Unity.

إذا لم يسبق للمستخدم استخدام &quotخدمات ألعاب Google Play" على جهازه، سيتم تلقائيًا توجيهه إلى شاشة الإعداد لمرة واحدة لإنشاء حساب على &quotألعاب Play".

في طريقة Start للبرنامج النصي، استمِع إلى نتيجة محاولة المصادقة التلقائية، واحصُل على حالة المصادقة، وأوقِف ميزات "خدمات ألعاب Play" إذا لم تتم مصادقة المستخدم.

إذا كان إصدار إضافة Unity أقدم من v11، لن تتمكّن من استخدام ميزة المصادقة.

    using GooglePlayGames;

    public void Start() {
      PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);
    }

    internal void ProcessAuthentication(SignInStatus status) {
      if (status == SignInStatus.Success) {
        // Continue with Play Games Services
      } else {
        // Disable your integration with Play Games Services or show a login button
        // to ask users to authenticate. Clicking it should call
        // PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).
      }
    }

رمز النتيجة هو تعداد يمكنك استخدامه لتحديد سبب تعذُّر المصادقة.

إذا كنت تفضّل استخدام منصة Social من Unity، يمكنك بدلاً من ذلك استخدام الرمز التالي:

  using GooglePlayGames;

  public void Start() {
    PlayGamesPlatform.Activate();
    Social.localUser.Authenticate(ProcessAuthentication);
  }

لا يمكنك إجراء أي طلبات إلى واجهة برمجة التطبيقات الخاصة بـ "خدمات ألعاب Google Play" إلى أن تحصل على قيمة إرجاع ناجحة من Authenticate. نتيجةً لذلك، ننصح الألعاب بعرض شاشة وضع الاستعداد إلى أن يتم استدعاء دالة الرجوع لضمان عدم تمكّن المستخدمين من بدء اللعب إلى أن تكتمل عملية المصادقة.

منع إنشاء الملفات الشخصية تلقائيًا

يمكنك إيقاف طلبات إنشاء الملف الشخصي التي يتم تشغيلها تلقائيًا من خلال ملف البيان. يتيح ذلك للمستخدمين الذين ليس لديهم ملف شخصي على "خدمات ألعاب Play" مواصلة تحميل اللعبة بدون أن يُطلب منهم إنشاء ملف شخصي على "خدمات ألعاب Play". لمزيد من المعلومات، يُرجى الاطّلاع على خيارات إنشاء الملف الشخصي.

لاستخدام هذه الميزة، تأكَّد من استيفاء الشروط التالية:

  1. في ملف AndroidManifest.xml، أضِف العلامة com.google.android.gms.games.SUPPRESS_GAME_PROFILE_CREATION في العنصر <meta-data> والسمات إلى العنصر <application>:

    <application>
    ...
    <meta-data
        android:name="com.google.android.gms.games.SUPPRESS_GAME_PROFILE_CREATION"
        android:value="true" />
    ...
</application>

    يؤدي ضبط هذا العلامة على "صحيح" إلى إعلام "خدمات ألعاب Play" بأنّ لعبتك ستتولى عملية إنشاء الملف الشخصي. وبالتالي، لن تعرض &quot;خدمات ألعاب Play&quot; تلقائيًا واجهة مستخدم لإنشاء ملف شخصي للمستخدمين الذين ليس لديهم ملف شخصي حالي على &quot;خدمات ألعاب Play&quot; على الجهاز.

  2. للتعامل مع الحالات التي لا تتم فيها مصادقة المستخدم بسبب عدم توفّر ملف شخصي في &quotخدمات ألعاب Play&quot، يمكنك استخدام PlayGamesPlatform.Instance.IsAuthenticated(). تعرض هذه الطريقة القيمة false لأنّ إنشاء الملف الشخصي يتعذّر. لحلّ هذه المشكلة، ابدأ عملية إنشاء الملف الشخصي من خلال استدعاء PlayGamesPlatform.Instance.ManuallyAuthenticate().

    
if (!PlayGamesPlatform.Instance.IsAuthenticated()) {
  // The user is unauthenticated, likely due to a missing Play Games profile.
  // Calling PlayGamesPlatform.Instance.ManuallyAuthenticate() will trigger
  // the profile creation UI.
  PlayGamesPlatform.Instance.ManuallyAuthenticate((SignInStatus status) => {
    // ...
  });
}

  3. بعد إضافة علامة الحظر، استخدِم النافذة logcat للتحقّق من عملية الإضافة. يحتوي الناتج logcat على رسالة مشابهة لما يلي: "تم إيقاف طلب إنشاء الملف الشخصي تلقائيًا في اللعبة (باستخدام ملف البيان)".

استخدام ميزة "توقيع التطبيق" من Play

تدير Google مفتاح توقيع تطبيقك وتحميه باستخدام ميزة "توقيع التطبيق" من Play. يمكنك استخدام ميزة "توقيع التطبيق" من Play لتوقيع حِزم مجموعة حزمات تطبيق Android (AAB) المحسَّنة للتوزيع. تخزّن ميزة "توقيع التطبيق" من Play مفتاح توقيع التطبيق على البنية الأساسية الآمنة لدى Google. لاستخدام ميزة "توقيع التطبيق" من Play، عليك أولاً إنشاء ملف AAB وتنزيله من Unity Editor. يمكنك بعد ذلك تحميل ملف AAB إلى Play Console وإنشاء إصدار للاختبار الداخلي.

إنشاء ملف AAB

لإنشاء ملف AAB في Unity Editor، اتّبِع الخطوات التالية:

  1. في Unity Editor، انقر على ملف (File) > إعدادات الإنشاء (Build settings).

  2. اختَر إنشاء حِزمة تطبيق ( Google Play).

    لمزيد من المعلومات، يُرجى الاطّلاع على مرجع إعدادات الإصدار على Android.

  3. انقر على إنشاء.

  4. نزِّل ملف AAB من Unity Editor.

إنشاء إصدار للاختبار الداخلي

لإنشاء إصدار اختبار داخلي وإضافة مختبِرين في Play Console، اتّبِع الخطوات التالية:

  1. في Google Play Console، اختَر لعبة.
  2. انتقِل إلى صفحة الاختبار والإصدار (الاختبار > الاختبار الداخلي).
  3. انقر على تحميل واختَر ملف AAB.
  4. في حقل تفاصيل الإصدار، أدخِل اسمًا.
  5. انقر على التالي وراجِع تفاصيل الإصدار.
  6. انقر على حفظ ونشر.

  7. في علامة التبويب المختبِرون، انقر على إنشاء قائمة عناوين بريد إلكتروني لإضافة ما يصل إلى 100 مختبِر.

    لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الاختبار الداخلي: إدارة ما يصل إلى 100 مختبِر.

  8. في عنوان URL أو عنوان البريد الإلكتروني المخصّص لتلقّي الملاحظات، أدخِل عنوان URL أو عنوان بريد إلكتروني لتلقّي الملاحظات.

  9. انقر على حفظ.

تأكيد بيانات اعتماد "توقيع التطبيق"

  1. في Google Play Console، اختَر لعبة.
  2. انتقِل إلى صفحة الاختبار والإصدار (الإعداد > توقيع التطبيق).
  3. تأكَّد من صحة بيانات اعتماد ميزة "توقيع التطبيق".

إنشاء المشروع وتشغيله

يمكنك إنشاء مشروع اللعبة وتشغيله في هذه المرحلة. عند بدء اللعبة، ستظهر لك محاولة المصادقة التلقائية.

يجب أن يكون لديك جهاز فعلي يعمل بنظام التشغيل Android مع تفعيل خيار تصحيح أخطاء الجهاز عبر USB أو محاكي يمكنه تشغيل المشروع الذي تم تطويره.

استرداد رموز مصادقة الخادم

للوصول إلى واجهات Google API على خادم ويب للخلفية نيابةً عن اللاعب الحالي، عليك الحصول على رمز مصادقة من تطبيق العميل وتمريره إلى تطبيق خادم الويب. يمكن بعد ذلك استبدال الرمز برمز دخول لإجراء طلبات إلى واجهات برمجة التطبيقات المختلفة. لمزيد من المعلومات حول سير العمل، يُرجى الاطّلاع على مقالة تسجيل الدخول باستخدام حساب Google على الويب.

للحصول على رمز الدخول من جهة الخادم، اتّبِع الخطوات التالية:

  1. أضِف معرّف عميل الويب الخاص بلعبتك في Play Console.
    1. في Google Play Console، اختَر لعبتك.
    2. في صفحة الإعدادات (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > الإعدادات)، انقر على إضافة بيانات اعتماد.
    3. في صفحة إضافة بيانات اعتماد، اختَر خادم الألعاب.
    4. إنشاء معرّف عميل OAuth 2.0
    5. سجِّل قيمة معرّف العميل. عليك تقديم هذه القيمة لاحقًا.

  2. أضِف معرّف عميل الويب إلى Unity Hub.

    1. في Unity Hub، اضبط إعدادات "ألعاب Google Play" في Unity وقم بالمصادقة.
    2. في Unity Hub، انتقِل إلى Window > ألعاب Google Play > Setup > إعداد Android.
    3. أدخِل قيمة معرّف العميل.

  3. استرداد رمز تفويض الخادم للنطاقات الإضافية

    #C

    using GooglePlayGames.BasicApi;

// Define selectedScope having additional identity scopes.
private List selectedScopes = new List();

// Add scopes you want to request.
selectedScopes.Add(AuthScope.OPEN_ID);
selectedScopes.Add(AuthScope.PROFILE);
selectedScopes.Add(AuthScope.EMAIL);

// Call RequestServerSideAccess with additional scopes and retrieve
// authcode and grantedscopes list.
PlayGamesPlatform.Instance.RequestServerSideAccess(
    /* forceRefreshToken= */ false,selectedScopes
    (AuthResponse authResponse) =>
    {
    string authCode = authResponse.GetAuthCode();
    List grantedScopes = authResponse.GetGrantedScopes();

    // send authCode to server...
});

إعداد الميزات وإضافتها