دمج حزمة تطوير البرامج (SDK) الخاصة بـ "ألعاب Google Play على الكمبيوتر" مع Unity

المشروع، مع توضيح الخطوات بدءًا من تنزيل حزمة تطوير البرامج (SDK) إلى إعدادها وتهيئة عملية الإنشاء keywords_public: ألعاب Google Play على الكمبيوتر، وUnity، ودمج حزمة تطوير البرامج (SDK)، والكمبيوتر الأصلي، وتطوير الألعاب، وIL2CPP، والبيان، وPlay Games PC Unity SDK

يقدّم هذا الدليل تعليمات مفصّلة حول كيفية دمج حزمة تطوير البرامج (SDK) لـ "ألعاب Google Play على الكمبيوتر" في مشروع Unity.

الخطوة 1: تنزيل حزمة تطوير البرامج (SDK)

نزِّل أحدث إصدار من حزمة Unity باستخدام رابط التنزيل.

تنزيل: حزمة تطوير البرامج (SDK) لإصدار Unity من "ألعاب Play على الكمبيوتر"

الخطوة 2: استيراد الحزمة

يتم توزيع حزمة تطوير البرامج (SDK) كملف tar متوافق مع Unity Package Manager (UPM). لمزيد من المعلومات، راجِع تثبيت حزمة UPM من ملف tar محلي

الخطوة 3: ضبط إعدادات الإصدار

للتحقّق من تحميل المكتبات الأصلية بشكل صحيح، يجب ضبط مشروعك لاستخدام IL2CPP كبرنامج الخلفية النصي واستهداف البنية الصحيحة.

1. أنشئ ملفًا شخصيًا للإصدار باستخدام Windows كمنصة.

2. اختَر إعدادات النظام الأساسي كـ Windows. بالنسبة إلى البنية، استخدِم الخيارات التالية:

   • معالج Intel‏ 64 بت (مُقترَح)
   • Intel 32-bit

   ملاحظة: تعمل منصة "ألعاب Google Play على الكمبيوتر" في بيئة 64 بت. يمكنك إنشاء لعبتك كإصدار 32 بت (x86) أو 64 بت (x64).

3. اضبط Scripting Backend على IL2CPP. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء مشروع باستخدام IL2CPP.

   • اضبط مستوى توافق واجهة برمجة التطبيقات على ‎.NET Standard 2.0 (أو ‎ .NET Framework).

الخطوة 4: إنشاء ملف بيان التطبيق

قبل أن تتمكّن من استخدام حزمة SDK في لعبتك، عليك ربط ملف تنفيذ اللعبة باسم حزمة Play الذي طالبْت به في Play Console. يمكنك إجراء ذلك من خلال إضافة ملف manifest.xml في الدليل نفسه الذي يحتوي على الملف التنفيذي للعبة.

ملاحظة: هذه خطوة يدوية يجب تنفيذها.

1. لإنشاء ملف قابل للتنفيذ للعبتك، اختَر ملف > إنشاء وتشغيل أو انقر على Ctrl+B.
2. افتح محرّر نصوص وأنشئ ملفًا جديدًا باسم manifest.xml.

3. انسخ رمز XML التالي وألصِقه في الملف:

   <?xml version="1.0" encoding="utf-8"?>
   <?Manifest version="1">
      <?Application>
        <?PackageName>com.example.package<?/PackageName>
      <?/Application>
   <?/Manifest>

4. احفظ الملف باسم manifest.xml.

5. انقل هذا الملف إلى المجلد نفسه الذي يحتوي على ملف اللعبة التنفيذي الذي تم إنشاؤه.

   مثال: إذا كانت لعبتك متوفرة على Builds/MyGame.exe، يجب أن يكون ملف البيان متوفرًا على Builds/manifest.xml.

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

الخطوة 5: إعداد حزمة تطوير البرامج (SDK)

يجب تهيئة حزمة SDK قبل الوصول إلى أي ميزات، مثل "الفوترة" أو "التحقّق من السلامة". استخدِم PlayPcSdkFactory لإنشاء معالج التهيئة وبدء الاتصال.

أنشئ نصًا برمجيًا جديدًا بلغة C# ‎، على سبيل المثال، SdkInitialization.cs، وأضِف الرمز التالي:

using UnityEngine;
using System;
using System.Threading.Tasks;
// Import the SDK namespaces
using PlayPcSdkManaged.Initialization;
using PlayPcSdkManaged.Unity;

public class GooglePlayPCSDKInit : MonoBehaviour
{
    // Prevent double-initialization if this script is reloaded
    private static bool _isInitialized = false;

    private void Start()
    {
        // Use the "Safe Runner" pattern to fire the async method
        _ = InitializeSdkAsync();
    }

    private async Task InitializeSdkAsync()
    {
        if (_isInitialized)
        {
            Debug.LogWarning("Google Play PC SDK is already initialized. Skipping.");
            return;
        }

        try
        {
            Debug.Log("Initializing Google Play PC SDK...");

            // 1. Get the Unity-specific initialization handler from the factory
            var initHandler = PlayPcSdkFactory.InitializationHandler;

            // 2. Call InitializeAsync to start the connection
            var result = await GooglePlayInitialization.InitializeAsync(initHandler);

            // 3. Check the result
            if (result.IsOk)
            {
                _isInitialized = true;
                Debug.Log("<color=green>Google Play PC SDK Initialized Successfully!</color>");
                // You can now create BillingClient or IntegrityClient instances
            }
            else
            {
                Debug.LogError($"<color=red>Initialization Failed!</color>");
                Debug.LogError($"Error Code: {result.Code}");
                Debug.LogError($"Message: {result.ErrorMessage}");
            }
        }
        catch (Exception ex)
        {
            // Catch unexpected crashes or task failures
            Debug.LogError($"Exception during initialization: {ex.Message}");
            Debug.LogException(ex);
        }
    }
}

أرفِق هذا النص البرمجي بـ GameObject في المشهد الأول. عند تشغيل اللعبة، ابحث في "وحدة التحكّم" عن الرسالة "تم إعداد حزمة تطوير البرامج (SDK) بنجاح".

الخطوة 6: تفعيل ميزة "التشغيل التلقائي" عند تثبيت "ألعاب الكمبيوتر الأصلية"

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

آلية العمل

عند تفعيل هذه الميزة، ستمرِّر GPG الرمز المميز لجلسة GPG إلى عملية التثبيت التابعة لجهة خارجية (3P) من خلال وسيطات سطر الأوامر. بعد ذلك، يكون برنامج التثبيت مسؤولاً عن استخراج هذا الرمز المميز واستخدامه لتشغيل ملف اللعبة التنفيذي في سياق مصادَق عليه.

المتطلبات الأساسية

لاستخدام هذه الميزة، يجب أن يكون برنامج التثبيت التابع لجهة خارجية قادرًا على التعامل مع وسيطات سطر الأوامر.

خطوات التنفيذ

1. تفعيل ميزة "التشغيل التلقائي" في إعدادات النشر

   لتفعيل هذه الميزة، أضِف السمة acceptsCommandLineArguments إلى العنصر <installer> في play_publishing_config.xml.

   مثال على محتوى manifest.xml:

   <installer requiresElevation="true" acceptsCommandLineArguments="true">
     <path>path/to/installer.exe</path>
     <installation-path-registry-location>
       <key-name>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\key</key-name>
       <value-name>InstallPath</value-name>
     </installation-path-registry-location>
   </installer>
   

   • السمة: acceptsCommandLineArguments
   • النوع: Boolean
   • عناوين URL التلقائية: false
   • السلوك: عند ضبط هذه السياسة على "صحيح"، سيضيف GPG الرمز المميز للجلسة إلى وسيطات سطر الأوامر عند تنفيذ برنامج التثبيت.

2. التعامل مع الرمز المميز للجلسة في برنامج التثبيت

   عندما يتم تشغيل برنامج التثبيت من خلال برنامج GPG، سيتلقّى الرمز المميز للجلسة كمعلَمة سطر أوامر.

   • تنسيق الوسيطة: --g_session_token=<TOKEN>

   الإجراءات التي يجب اتّخاذها:

   • الاستخراج: يجب أن تحلّل أداة التثبيت وسيطات سطر الأوامر لاسترداد سلسلة الرمز المميّز.
   • نقل الرمز المميّز: إذا كانت عملية التثبيت تتضمّن تشغيل عملية ثانوية لتشغيل التطبيق أو اللعبة، يكون برنامج التثبيت مسؤولاً عن نقل الرمز المميّز للجلسة بشكل آمن إلى عملية اللعبة النهائية التي تستخدم حزمة SDK.
   • التشغيل: استخدِم الرمز المميز للجلسة المقدَّم لبدء تنفيذ اللعبة. يضمن ذلك تشغيل اللعبة ضمن سياق مصادقة "خدمات ألعاب Google Play". وفي حال عدم توفّرها، سيتعذّر تنفيذ InitializeSDK وسيكون على اللاعب إعادة تشغيل اللعبة.

3. معالجة الأخطاء والبدائل

• استرداد الرمز المميز: إذا تعذّر على GPG لأي سبب إنشاء رمز مميز للجلسة أو تمريره (مثل تعذّر إنشاء الرمز المميز)، ستستمر عملية التثبيت. ومع ذلك، سيتم تشغيل برنامج التثبيت بدون الوسيطة --g_session_token.
• المتانة: يجب تصميم برنامج التثبيت للتعامل مع الحالات التي لا يتوفّر فيها الرمز المميّز للجلسة. في مثل هذه الحالات، يجب أن تواصل أداة التثبيت عملية التثبيت العادية، ويجب ألا تبدأ تشغيل اللعبة تلقائيًا لأنّ InitializeSDK ستتعذّر على أي حال.
• أخطاء برنامج التثبيت: أنت المسؤول عن قوة برنامج التثبيت والتعامل مع الأخطاء وتسلسل تشغيل اللعبة الذي يبدأه برنامج التثبيت. لا تتحكّم GPG في العمليات التي تحدث داخل أداة التثبيت بعد تشغيلها.