שיפור המשחק באמצעות Play Games PC SDK

בעזרת Play Games PC SDK, אפשר לגשת לשירותי Google Play כדי ליצור משחקים למחשבים אישיים ולייצר מהם הכנסות. אפשר למכור תוכן דיגיטלי באמצעות מערכת החיוב של Play, להיכנס לחשבון בצורה חלקה באמצעות Play Games ולאמת שלמשתמשים יש זכאות תקפה לאפליקציה באמצעות Play Integrity.

מוכנים להתחיל?

דרישות מוקדמות

• יוצרים רשומה של אפליקציה ב-Play Console ומגדירים שם חבילה ב-Play.

• מורידים ומתקינים את Google Play Games במחשב ונכנסים לחשבון Google.

שלב 1: מוסיפים את ה-SDK לפרויקט

שלב 2: הוספת קובץ מניפסט

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

תוכן manifest.xml לדוגמה:

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

מיקום manifest.xml לדוגמה:

C:\Program Files
└───Example Game
    ├───Game.exe
    └───manifest.xml

שלב 3: חותמים על המשחק בחתימה דיגיטלית

כדי שהמשחק יוכל להשתמש ב-SDK, צריך לחתום על קובץ ההפעלה של המשחק בחתימה דיגיטלית באמצעות חתימה דיגיטלית של Authenticode. הוראות לחתימה על קובץ הפעלה מופיעות במאמרי העזרה בנושא SignTool .

אחרי שתשלימו את התהליך של חתימה דיגיטלית על המשחק, תצטרכו לשלוח את פרטי האישור לנציג שלכם ב-Google לצורך הגדרה.

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

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

כדי להתחיל להשתמש ב-SDK, קוראים ל-GooglePlayInitialize (C++) / GooglePlayInitialization.InitializeAsync (C#) כדי לאתחל את ה-API. הפעולה הזו תגדיר מצב גלובלי, תתחבר לזמן הריצה של ה-SDK ותאמת שהאפליקציה הופעלה בצורה תקינה. חובה לקרוא לפונקציה הזו ולהשלים את הקריאה החוזרת להמשך עם InitializeResult::ok() (C++) או Result.IsOk (C#) ששווה ל-true לפני שמשתמשים ב-API אחר.

  // Initialize the SDK as part of the startup sequence of your application.
  auto promise = std::make_shared<std::promise<InitializeResult>>();
  GooglePlayInitialize(
    [promise](InitializeResult result) {
      promise->set_value(std::move(result));
    });

  auto initialize_result = promise->get_future().get();
  if (initialize_result.ok()) {
    // The SDK succeeded with initialization. Continue with the startup sequence
    // of the game.
    // ...
  } else if (initialize_result.code() == InitializationError::kActionRequiredShutdownClientProcess) {
    // The SDK failed to initialize and has requested that your game process exit
    // as soon as possible.
    exit(1);
  } else {
    // The SDK failed to initialize for an alternative reason. It is still
    // generally recommended that you exit the game process as soon as possible,
    // because it won't be possible to access any APIs in the SDK. Critical
    // operations such as verifying the user owns a valid license to your game
    // won't be possible.
    // ...
  }

  // SDK Clients
  private BillingClient _billingClient;
  private IntegrityClient _integrityClient;

  // Stored product information
  private string _offerToken;

  private async void InitializeSDK()
  {
      // The factory provides the necessary handler for initialization.
      var initializationHandler = PlayPcSdkFactory.InitializationHandler;
      var result = await GooglePlayInitialization.InitializeAsync(initializationHandler);

      if (result.IsOk)
      {
          // Use the factory to get Unity-compatible instances of the clients
          _billingClient = PlayPcSdkFactory.CreateBillingClient();
          _integrityClient = PlayPcSdkFactory.CreateIntegrityClient();

          // SDK is ready for use
      }
      else
      {
          // Handle specific, actionable errors
          if (result.Code == InitializationError.ActionRequiredShutdownClientProcess)
          {
              Log("This game must be launched through the Google Play Games client. Please exit all game processes immediately, GPG will relaunch the game safely.");
              Application.Quit();
          }
      }
  }

אם האתחול נכשל עם הקוד kActionRequiredShutdownClientProcess (C++) / InitializationError.ActionRequiredShutdownClientProcess (C#), צריך לצאת מתהליך המשחק בהקדם האפשרי. זמן הריצה של ה-SDK ינסה לעזור למשתמש, בלי שהמשחק יצטרך לבצע פעולה נוספת. לדוגמה, אם למשתמש אין רישיון תקף למשחק, המערכת של Google Play Games תציג למשתמש בקשה לרכוש עותק. במקרה של שגיאות אחרות, צריך לצאת מתהליך המשחק כי לא תוכלו להשתמש ב-SDK כדי לבצע פעולות קריטיות, כמו אימות שלרישיון של המשתמש למשחק יש תוקף.

תגובה לא מוצלחת עשויה להצביע על אחד מהתנאים הבאים:

• זמן הריצה של ה-SDK לא מותקן, לא פועל במכשיר או שהוא גרסה ישנה שלא תואמת ל-SDK שמשולב במשחק.

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

• קובץ ההפעלה של המשחק לא הופעל דרך לקוח Google Play Games.

• למשתמש הפעיל ב-Google Play Games אין רישיון לאפליקציה.

שלב 5: (אופציונלי) תמיכה בכמה תהליכי משחק

אם המשחק שלכם משתמש בכמה תהליכים, וערכת ה-SDK של Play Games למחשב משמשת תהליך שונה מזה שמופעל על ידי Google Play Games במחשב, צריך לבצע את שלבי השילוב הנוספים האלה. לדוגמה, אם Google Play Games במחשב מפעיל את כלי ההפעלה של המשחק, ואז כלי ההפעלה מפעיל את תהליך המשחק שמתקשר עם ה-SDK.

1. התהליך שמופעל ישירות על ידי Google Play Games במחשב צריך לאמת אתחול מוצלח של Play Games PC SDK.

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

2. כדי להשתמש ב-Play Games PC SDK בתהליך צאצא, צריך להעביר את הפרמטרים של שורת הפקודה לתהליך הצאצא שנוצר.

   דוגמה להעברת פרמטרים של שורת פקודה:

   Processes hierarchy tree:
   
   GooglePlayGames.exe
   └───YourGameLauncher.exe --gpg_args=abc --your_args=123
       └───YourGame.exe --gpg_args=abc --your_args=123
   

   בדוגמה הזו אפשר לראות היררכיית תהליכים שבה Google Play Games למחשב (GooglePlayGames.exe) מפעיל את המשחק (YourGameLauncher.exe) עם כמה פרמטרים לדוגמה (--gpg_args=abc --your_args=123). לאחר מכן המשחק יוצר תהליך צאצא (YourGame.exe) שמשתמש ב-SDK של Play Games למחשב. כדי לאפשר את זה, תהליך המשחק שהופעל על ידי Google Play Games למחשב מעביר את הפרמטרים של שורת הפקודה שניתנו לו לתהליך הצאצא.

3. יציאה מכל התהליכים כשהמשחק מפסיק לפעול.

   כשמשתמש סוגר את המשחק או כשהמשחק יוצא בגלל כשל בהפעלת SDK, כמו kActionRequiredShutdownClientProcess, צריך לסגור את כל התהליכים שהמשחק יצר. כך תוכלו לוודא שבפעם הבאה שהמשחק יופעל על ידי לקוח Google Play Games למחשב, שינויים חדשים כמו מעבר לחשבון פעיל אחר ייכנסו לתוקף.

השלבים הבאים

שימוש ב-SDK במהלך פיתוח בסביבת הפיתוח המשולבת (IDE):

• הפעלה של מצב פיתוח

הוספת תכונות של Google Play למחשב לאפליקציה:

• מכירת מוצרים דיגיטליים באמצעות חיוב ב-Play
• מדידת ביצועי השיווק באמצעות הפניה להתקנה מחנות Play
• הגנה על המשחק באמצעות Play Integrity למחשב