שילוב של Google Play Games PC SDK עם Unity

בפרויקט, כולל השלבים מהורדת ה-SDK ועד להגדרה של ההפעלה והבנייה. keywords_public: Google Play Games PC, Unity, SDK integration, native PC, game development, IL2CPP, manifest, Play Games PC Unity SDK

במדריך הזה מוסבר איך לשלב את Google Play Games PC SDK בפרויקט Unity.

שלב 1: מורידים את ה-SDK

מורידים את הגרסה האחרונה של חבילת Unity באמצעות קישור ההורדה.

הורדה: SDK של Play Games למחשב Unity

שלב 2: ייבוא החבילה

ערכת ה-SDK מופצת כקובץ tar שתואם ל-Unity Package Manager‏ (UPM). מידע נוסף זמין במאמר בנושא התקנת חבילת UPM מקובץ tar מקומי

שלב 3: קביעת הגדרות הבנייה

כדי לוודא שהספריות המקוריות נטענות בצורה תקינה, צריך להגדיר את הפרויקט כך שישתמש בIL2CPP scripting backend ויטרגט את הארכיטקטורה הנכונה.

1. יוצרים פרופיל build עם Windows כפלטפורמה.

2. בוחרים באפשרות הגדרות הפלטפורמה בתור Windows. באפשרות ארכיטקטורה, משתמשים באפשרויות:

   • ‫Intel 64-bit (מומלץ)
   • Intel 32-bit

   הערה: פלטפורמת Google Play Games במחשב פועלת בסביבת 64 ביט. אפשר ליצור את המשחק כגרסת 32 ביט (x86) או כגרסת 64 ביט (x64).

3. מגדירים את Scripting Backend (קצה עורפי של סקריפטים) ל-IL2CPP. מידע נוסף זמין במאמר בנושא יצירת פרויקט באמצעות IL2CPP.

   • מגדירים את Api Compatibility Level (רמת התאימות של ה-API) ל-‎.NET Standard 2.0 (או ל-‎ .NET Framework).

שלב 4: יצירת מניפסט האפליקציה

לפני שמשתמשים ב-SDK במשחק, צריך לשייך את קובץ ההפעלה של המשחק לשם החבילה ב-Play שרשמתם ב-Play Console. כדי לעשות את זה, מוסיפים קובץ manifest.xml לאותה תיקייה שבה נמצא קובץ ההפעלה של המשחק.

הערה: זהו שלב ידני שחובה לבצע.

1. כדי ליצור את קובץ ההפעלה של המשחק, בוחרים באפשרות File > Build and Run (קובץ > יצירה והפעלה) או לוחצים על 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 Games. שלבים נוספים להגדרת קובץ המניפסט מפורטים במדריך להגדרת מצב פיתוח.

שלב 5: אתחול ה-SDK

צריך להפעיל את ה-SDK לפני שמשתמשים בתכונות כמו חיוב או יושרה. משתמשים ב-PlayPcSdkFactory כדי ליצור את ה-handler לאתחול ולהתחיל את החיבור.

יוצרים סקריפט חדש של 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 Initialized Successfully!‎ (ה-SDK הופעל בהצלחה).

שלב 6: הפעלת ההפעלה האוטומטית אחרי ההתקנה של משחקים מקוריים למחשב

פלטפורמת Google Play Games למחשב (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
   • ברירת המחדל: false
   • התנהגות: אם מגדירים את הערך כ-True, ‏ GPG מוסיף את טוקן הסשן לארגומנטים של שורת הפקודה כשמריצים את קובץ ההתקנה.

2. טיפול בטוקן הסשן בכלי ההתקנה

   כשלקוח GPG מפעיל את קובץ ההתקנה, הוא מקבל את אסימון הסשן כארגומנט בשורת הפקודה.

   • פורמט הארגומנט: --g_session_token=<TOKEN>

   מה צריך לעשות:

   • חילוץ: תוכנת ההתקנה צריכה לנתח את הארגומנטים של שורת הפקודה כדי לאחזר את מחרוזת הטוקן.
   • הפצה: אם תהליך ההתקנה שלכם כולל הפעלה של תהליך משני של מרכז האפליקציות או של המשחק, תוכנת ההתקנה אחראית להעברת אסימון הסשן בצורה מאובטחת לתהליך הסופי של המשחק שמשתמש ב-SDK.
   • הפעלה: משתמשים באסימון הסשן שסופק כדי להפעיל את קובץ ההפעלה של המשחק. כך מוודאים שהמשחק פועל בהקשר מאומת של GPG. אחרת, הפונקציה InitializeSDK תיכשל והשחקן יצטרך להפעיל מחדש את המשחק.

3. טיפול בשגיאות וגיבויים

• אחזור טוקן: אם מסיבה כלשהי, GPG לא יכול ליצור או להעביר טוקן סשן (למשל, אם יצירת הטוקן נכשלה), תהליך ההתקנה ימשיך בכל זאת. עם זאת, תוכנית ההתקנה תופעל ללא הארגומנט ‎--g_session_token.
• חוסן: תוכנת ההתקנה צריכה להיות מתוכננת כך שתדע להתמודד עם תרחישים שבהם אין טוקן סשן. במקרים כאלה, תוכנת ההתקנה צריכה להמשיך בהתקנה רגילה. לא צריך להפעיל את המשחק באופן אוטומטי כי הפונקציה InitializeSDK תיכשל בכל מקרה.
• שגיאות בהתקנה: אתם אחראים לחוסן ולטיפול בשגיאות של תוכנת ההתקנה ושל רצף הפעלת המשחק שהיא יוזמת. ל-GPG אין שליטה בתהליכים שמתרחשים בתוך קובץ ההתקנה אחרי שהוא מופעל.