שיפור המשחק באמצעות 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: (אופציונלי) תמיכה בכמה תהליכי משחק

אם המשחק שלכם משתמש בכמה תהליכים, והתהליך שמשתמש ב-Play Games PC SDK שונה מהתהליך שמופעל על ידי 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 למחשב לאפליקציה:

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