שיפור המשחק באמצעות 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 לפרויקט

C++‎

  • מורידים את ה-SDK של C++ Play Games למחשב.

  • מעתיקים את תיקיית כותרות ה-API‏ includes/ אל בסיס הקוד של האפליקציה.

  • מעתיקים את הקבצים להפצה חוזרת מהספרייה imports/ לפרויקט של האפליקציה, בהתאם לארכיטקטורת היעד:

  • במערכות 64 ביט (x64): מעתיקים את הקבצים מ-imports/x64/.

  • במערכת 32 ביט (x86): מעתיקים את הקבצים מ-imports/x86/.

  • מקשרים את הפרויקט ל-play_pc_sdk.lib כדי לאפשר גישה לתוכן של play_pc_sdk.dll.

C#‎

שלב 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, צריך לקרוא ל-API באמצעות GooglePlayInitialize (C++) או GooglePlayInitialization.InitializeAsync (C#) כדי לאתחל אותו. מומלץ להעביר את שם החבילה של המשחק ב-Android בפרמטר GooglePlayInitializeParams במהלך האתחול. הפעולה הזו מגדירה מצב גלובלי, מתחברת לזמן הריצה של ה-SDK ומאמתת שהאפליקציה הופעלה בצורה תקינה. צריך לבצע את הקריאה הזו ולחכות עד שהקריאה החוזרת להמשך תסתיים עם InitializeResult::ok() (C++) או Result.IsOk (C#) ששווה ל-true, לפני שמשתמשים ב-API אחר.

C++‎

// Initialize the SDK as part of the startup sequence of your
// application.
auto promise = std::make_shared<std::promise<InitializeResult>>();
GooglePlayInitializeParams params;
// Replace with your game's package name.
params.package_name = "com.example.game";
GooglePlayInitialize(
  [promise] (InitializeResult result) {
    promise->set_value(std::move(result));
  }, params);

auto initialize_result = promise->get_future().get();
if (initialize_result.ok()) {
  // The SDK succeeded with initialization. Continue with the startup
  // sequence of the game.
  // ...

  // Retrieve the operating environment and device form factor.
  auto env = initialize_result.value().environment;
  auto form_factor = initialize_result.value().form_factor;
  // ...
} 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.
  // ...
}

C#‎

// 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 initializeParams = new GooglePlayInitializeParams {
        // Replace with your game's package name.
        PackageName = "com.example.game"
    };
    var result = await GooglePlayInitialization.InitializeAsync(
        initializationHandler, initializeParams);

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

        // Retrieve the operating environment and device form factor.
        var env = result.Value.Environment;
        var form_factor = result.Value.FormFactor;

        // 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 למחשב לאפליקציה: