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

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

סקירה כללית של התכונות הקרובות, הגרסאות היציבות וארכיטקטורת השילוב זמינה בתוכנית הפיתוח של Play Games במחשב.

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

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

• יוצרים רשומה של אפליקציה ב-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. 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 למחשב