פרסום של קובץ התקנה

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

בתהליך "התקנה על ידי המפתח", מנהל ההתקנה של המשחק שאתם מספקים צריך לנהל את ההתקנה, העדכון וההסרה של המשחק.

לפני שמתחילים

משלבים את Google Play Games SDK במשחק.

אריזת המשחק כקובץ WAB

כדי להפעיל את Google Play Games במחשב, צריך להעלות את קובץ ההתקנה של המשחק ל-Google Play Console כקובץ Windows App Bundle‏ (WAB). כדי ליצור קובץ WAB, פועלים לפי השלבים הבאים:

  1. מורידים את כלי הפרסום של Play. אפשר להריץ את הכלי הזה בשורת הפקודה של Windows או ב-PowerShell.

  2. יוצרים את קובץ התצורה של הפרסום ב-Play, ונותנים לו שם כלשהו. לדוגמה, play_publishing_config.xml בפורמט הבא:

    <?xml version="1.0" encoding="UTF-8"?>
    <play-publishing-config version="1.0">
      <application>
        <package-name>PACKAGE_NAME</package-name>
        <version-name>VERSION_NAME</version-name>
      </application>
      <installer requiresElevation=INSTALLER_REQUIRES_ELEVATION acceptsCommandLineArguments=ACCEPTS_COMMAND_LINE_ARGUMENTS>
        <path>INSTALLER_PATH</path>
        <installation-path-registry-location>
          <key-name>UNIQUE_REGISTRY_PATH</key-name>
          <value-name>InstallLocation</value-name>
        </installation-path-registry-location>
      </installer>
      <launcher requiresElevation=LAUNCHER_REQUIRES_ELEVATION>
        <launch-path-registry-location>
          <key-name>UNIQUE_REGISTRY_PATH</key-name>
          <value-name>InstallLocation</value-name>
        </launch-path-registry-location>
        <executable-invocation>
          <filename>RELATIVE_PATH_TO_LAUNCHER_EXE</filename>
          <arguments>LAUNCHER_ARGS_IF_ANY</arguments>
        </executable-invocation>
      </launcher>
      <uninstaller requiresElevation=UNINSTALLER_REQUIRES_ELEVATION>
        <uninstall-path-registry-location>
          <key-name>UNIQUE_REGISTRY_PATH</key-name>
          <value-name>UninstallString</value-name>
        </uninstall-path-registry-location>
      </uninstaller>
    </play-publishing-config>

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PACKAGE_NAME: שם החבילה של המשחק. זה המזהה הייחודי שישויך למשחק שלכם ב-Google Play. לדוגמה, com.yourcompany.yourgame. שם החבילה חייב לעמוד בכללים הבאים:
      • הוא חייב להכיל לפחות שני חלקים (נקודה אחת או יותר).
      • כל מקטע חייב להתחיל באות.
      • כל התווים חייבים להיות אלפאנומריים או קו תחתון ([a-zA-Z0-9_]).
    • ‫VERSION_NAME: מחרוזת הגרסה של המשחק. המחרוזת יכולה להיות שרירותית, אבל היא חייבת להיות ייחודית בכל קובצי ה-WAB שהועלו למשחק. לדוגמה: 1.0, 1.0.1-beta, 2025.11.24, v1.rc1.

      • ‫INSTALLER_REQUIRES_ELEVATION: מציין אם צריך להריץ את קובץ ההפעלה של מנהל ההתקנה כאדמין כדי להשלים את תהליך ההתקנה.

        • "true": הפעלת קובץ ההפעלה כמנהל מערכת.
        • ‫"false": הפעלת קובץ ההפעלה בתור המשתמש הנוכחי.
      • ‫ACCEPTS_COMMAND_LINE_ARGUMENTS: ערך בוליאני שמציין אם תוכנת ההתקנה יכולה לקבל ארגומנטים של שורת הפקודה כדי להפעיל את תכונת ההפעלה האוטומטית. השדה הזה הוא אופציונלי וערך ברירת המחדל שלו הוא False. מידע נוסף זמין במאמר הפעלת Auto-Play.

      • ‫INSTALLER_PATH: הנתיב לקובץ ההתקנה בתוך ה-WAB. הנתיב יכול להיות מוחלט או יחסי לספריית האם של הגדרת הפרסום ב-Play. לדוגמה, path\to\test\installer. חשוב לזכור להשתמש ב-Authenticode ובחתימת קוד כדי לחתום על קובץ ההפעלה של תוכנת ההתקנה של המשחק.

      • ‫<installation-path-registry-location>: הנתיב לרישום שמשמש את Google Play Games כדי לזהות אם המשחק מותקן. גם אם המשחק משתמש במרכז אפליקציות בהתאמה אישית, הנתיב הזה חייב להצביע על מפתח הרישום הייחודי של המשחק, ולא על מפתח הרישום של מרכז האפליקציות.

      • ‫UNIQUE_REGISTRY_PATH: הנתיב של מפתח הרישום של Windows. הנתיב הזה צריך להיות יחסי לכוורת רישום כמו HKEY_LOCAL_MACHINE או HKEY_CURRENT_USER. אל תכללו את שם הכוורת במחרוזת הנתיב. לדוגמה, אם תוכנת ההתקנה כותבת אל HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName, צריך לציין רק את Software\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName. ‫Google Play Games במחשב מחפש את הנתיב הזה קודם ב-HKEY_LOCAL_MACHINE ואז ב-HKEY_CURRENT_USER, ומשתמש בערך התואם הראשון שהוא מוצא.

        קובץ ההפעלה שצוין ב-INSTALLER_PATH חייב ליצור את מפתחות הרישום האלה. לפני שההתקנה מסתיימת, צריך ליצור את הצמדים האלה של מפתח רישום ושם ערך שצוינו בקטעים installation-path-registry-location,‏ launch-path-registry-location ו-uninstall-path-registry-location. בדוגמה הזו השתמשנו ב-InstallLocation וב-UninstallString, אבל אתם יכולים לציין כל שם בתגי <value-name> האלה, כל עוד תוכנת ההתקנה יוצרת רשומות תואמות ב-Registry לשלושתם. אפליקציית Google Play Games במחשב משתמשת בערכים האלה כדי להפעיל ולהסיר את המשחק. אם המשחק משתמש במרכז אפליקציות, הערך ברשומת המרשם שצוינה על ידי launch-path-registry-location חייב להצביע על הספרייה של מרכז האפליקציות (בעוד ש-installation-path-registry-location חייב להצביע על מפתח המרשם הייחודי של המשחק, ולא על מפתח המרשם של מרכז האפליקציות).

        הנתיב הזה חייב להיות ייחודי במחשב של המשתמש. לדוגמה: SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName.

        אם תוכנת ההתקנה של המשחק היא אפליקציית 32 ביט שפועלת ב-Windows בגרסת 64 ביט, מערכת Windows משתמשת בהפניה אוטומטית של המרשם כדי לכתוב רשומות מרשם ב-HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node. לדוגמה, פעולת כתיבה ב-HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName מופנית מחדש אל HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName.

      • ‫LAUNCHER_REQUIRES_ELEVATION: מציין אם צריך להריץ את קובץ ההפעלה של המשגר או המשחק כאדמין בכל פעם שמפעילים אותו.

        • "true": הפעלת קובץ ההפעלה כמנהל מערכת.
        • ‫"false": הפעלת קובץ ההפעלה בתור המשתמש הנוכחי.
      • ‫RELATIVE_PATH_TO_LAUNCHER_EXE: הנתיב לקובץ ההפעלה של המשגר או המשחק בספריית ההתקנה. השם צריך לכלול את שם הקובץ של מפעיל המשחק או של קובץ ההפעלה של המשחק. לדוגמה, אם המפעיל או קובץ המשחק נקרא mygame.exe והוא ממוקם בנתיב {INSTALL_DIR}\Resources\mygame.exe, צריך להזין Resources\mygame.exe

      • ‫LAUNCHER_ARGS_IF_ANY: כל הארגומנטים של שורת הפקודה שצריך להעביר למשגר או למשחק. הערך הזה הוא אופציונלי.

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

        • "true": הפעלת קובץ ההפעלה כמנהל מערכת.
        • ‫"false": הפעלת קובץ ההפעלה בתור המשתמש הנוכחי.

    קובץ תצורה לדוגמה לפרסום ב-Play

    נניח שיש משחק בשם MyGame, עם מנהל ההתקנה של המשחק game_installer.exe ומרכז האפליקציות של המשחק launcher.exe. בדוגמה אפשר גם לראות איך משתמשים ב-CDATA. ככה נראה play_publishing_config.xml:

    <?xml version="1.0" encoding="UTF-8"?>
    
    <play-publishing-config version="1.0">
      <application>
        <!-- The package name for your game. -->
        <package-name>com.mycompany.mygame</package-name>
        <!-- The game's version string. -->
        <version-name>1.0.0</version-name>
      </application>
      <!-- If requiresElevation is "true", installer runs as Administrator
           and a UAC prompt is displayed. This is required for system-wide
           installs (e.g., to Program Files) or writing to HKLM. -->
      <!-- If acceptsCommandLineArguments is "true", the installer must
           be able to accept command-line arguments to enable the auto-play
           feature. -->
      <installer requiresElevation="true" acceptsCommandLineArguments="true">
        <!-- Path to your installer executable. -->
        <path>game_installer.exe</path>
        <!-- The registry location where the installer writes the installation path. -->
        <installation-path-registry-location>
          <!-- Registry key path (typically under HKLM or HKCU).
               game_installer.exe MUST create this key. -->
          <key-name>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MySystemWideUniqueKey</key-name>
          <!-- game_installer.exe, specified in <path>, creates the registry
               value called 'InstallLocation' within
               SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MySystemWideUniqueKey
               by the time it exits. -->
          <value-name>InstallLocation</value-name>
        </installation-path-registry-location>
      </installer>
    
      <!-- If requiresElevation is "true", launcher runs as Administrator
           and a UAC prompt is displayed on every game launch. -->
      <launcher requiresElevation="true">
        <!-- Specifies the registry location where Google Play Games reads the installation path
             in order to launch the game. -->
        <launch-path-registry-location >
          <!-- Registry key path (typically under HKLM or HKCU) where
               the launch path can be found. -->
          <key-name>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MySystemWideUniqueKey</key-name>
          <!-- Google Play Games reads the installation directory from this
               registry value, for example InstallLocation, to launch the game. -->
          <value-name>InstallLocation</value-name>
        </launch-path-registry-location>
        <executable-invocation>
          <!-- Game executable or launcher filename, relative to the
               directory path specified in the InstallLocation registry value. -->
          <filename>launcher.exe</filename>
          <!-- Optional arguments to pass to the executable.
               CDATA is used here to avoid issues with special characters
               like & or >. -->
          <arguments><![CDATA[arg1&arg2>arg3]]></arguments>
        </executable-invocation>
      </launcher>
    
      <!-- If requiresElevation is "true", uninstaller runs as
           Administrator and a UAC prompt is displayed for uninstall. -->
      <uninstaller requiresElevation="true">
        <!-- Registry key where Google Play Games finds the
             uninstallation command. -->
        <uninstall-path-registry-location>
          <!-- Registry key path (typically under HKLM or HKCU) where
               uninstall command can be found. -->
          <key-name>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MySystemWideUniqueKey</key-name>
          <!-- game_installer.exe also creates the registry value, for example, 'UninstallString'
               within SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\MySystemWideUniqueKey,
               containing the command Google Play Games executes to uninstall
               the game. -->
          <value-name>UninstallString</value-name>
        </uninstall-path-registry-location>
      </uninstaller>
    </play-publishing-config>
    
  3. מריצים את כלי הפרסום של Play בשורת הפקודה של Windows או ב-Powershell.

    playpublishingtool.exe build-installer-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH
    

    כדי להחליף קובץ WAB קיים עם אותו שם, משתמשים בארגומנט --force.

    playpublishingtool.exe build-installer-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH --force
    

    מחליפים את מה שכתוב בשדות הבאים:

    • ‫PLAY_PUBLISHING_CONFIG_PATH: הנתיב לקובץ ההגדרות של הפרסום ב-Play. לדוגמה, path\to\play_publishing_config.xml.
    • ‫WAB_OUTPUT_PATH: הנתיב לקובץ ה-WAB. לדוגמה, path\to\output_bundle.wab.

    איך משתמשים בכלי הפרסום של Play

    נניח שיש לכם את הקובץ הבינארי של כלי הפרסום ב-Play‏ playpublishingtool.exe, את קובץ התצורה של הפרסום ב-Play‏ play_publishing_config.xml ואת קובץ ההתקנה של המשחק game_installer.exe בספריית העבודה הנוכחית.

    ספריית העבודה הנוכחית אמורה להיראות כך:

    .\
    ├── game_installer.exe
    ├── play_publishing_config.xml
    ├── playpublishingtool.exe
    

    כדי ליצור WAB בשם installer_bundle.wab באותה ספרייה, הפקודה תיראה כך:

    playpublishingtool.exe build-installer-bundle --input=play_publishing_config.xml --output=installer_bundle.wab
    

    עם הארגומנט --force, הפקודה תיראה כך:

    playpublishingtool.exe build-installer-bundle --input=play_publishing_config.xml --output=installer_bundle.wab --force
    

    אם הפעולה תצליח, הפלט אמור להיראות כך:

    Successfully built the installer bundle at installer_bundle.wab
    

    מוצאים את קובץ ה-WAB בתיקייה:

      .\
      ├── game_installer.exe
      ├── installer_bundle.wab
      ├── play_publishing_config.xml
      ├── playpublishingtool.exe
    

    הפעלת Auto-Play אחרי ההתקנה של משחקים מקוריים למחשב (אופציונלי)

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

    איך זה עובד

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

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

    כדי להשתמש בתכונה הזו, תוכנת ההתקנה של צד ג' צריכה להיות מסוגלת לטפל בארגומנטים של שורת הפקודה.

    שלבי הטמעה

    1. הפעלת ההפעלה האוטומטית בהגדרות הפרסום ב-Play

      כדי להצטרף לתכונה הזו, צריך להוסיף את המאפיין acceptsCommandLineArguments לאלמנט <installer> ב-play_publishing_config.xml.

      דוגמה לקטע מתוך התוכן של play_publishing_config.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 אין שליטה על תהליכים שמתרחשים בתוך תוכנת ההתקנה אחרי שהיא הופעלה.

מפרסמים את המשחק באמצעות Play Console

אחרי שיוצרים את ה-WAB למשחק, מעלים אותו ל-Play Console ומנהלים את ההגדרות והדרישות שלו. כדי לפרסם את המשחק, פועלים לפי השלבים הבאים:

הוספת גורם הצורה "Google Play Games במחשב"

צריך לבצע את השלב הזה רק בפעם הראשונה שמפרסמים משחק.

  1. בתפריט הימני של Play Console, לוחצים על בדיקה והשקה > הגדרה > הגדרות מתקדמות (קישור ישיר).
  2. עוברים לכרטיסייה גורמי צורה ומוסיפים את Google Play Games on PC מהתפריט הנפתח + הוספת גורם צורה.

  3. בצד שמאל, לוחצים על ניהול לצד גורם הצורה Google Play Games במחשב.

  4. בוחרים באפשרות שימוש במסלול ייעודי למשחק ב-Windows App Bundle.

  5. לוחצים על שמירה ואז שוב על שמירה בתיבת הדו-שיח לאישור.

הפעלת פרסום מנוהל

כדי להפעיל את התכונה "פרסום מנוהל", פועלים לפי השלבים הבאים.

  1. בדף סיכום השינויים לפרסום, בקטע פרסום מנוהל, לוחצים על הפעלת פרסום מנוהל.
  2. תופיע תיבת דו-שיח. מעבירים את המסלול למצב פרסום מנוהל מופעל.
  3. לוחצים על שמירה.

העלאת קובץ ה-WAB

כדי להעלות את קובץ ה-WAB, פועלים לפי השלבים הבאים:

  1. בתפריט הימני של Play Console, בוחרים באפשרות בדיקה והשקה > הגדרות מתקדמות (קישור ישיר).
  2. בדף הגדרות מתקדמות, לוחצים על הכרטיסייה גורמי צורה.
  3. בכרטיסייה גורמי צורה, לוחצים על + הוספת גורם צורה ובוחרים באפשרות Google Play Games במחשב כדי להוסיף אותו.
  4. בקטע Google Play Games במחשב, לוחצים על ניהול.
  5. בוחרים באפשרות שימוש במסלול ייעודי למשחק ב-Windows App Bundle.
  6. לוחצים על שמירה.
  7. בתפריט הימני של Play Console, בוחרים באפשרות בדיקה והשקה > גרסת ייצור (קישור ישיר).
  8. בדף Production, בוחרים באפשרות Google Play Games במחשב בלבד (Windows) מהתפריט הנפתח של גורם הצורה.
  9. בכרטיסייה חבילת אפליקציות ל-Windows, לוחצים על עריכה ומעלים את קובץ ה-WAB.

הגדרת הדרישות למחשבים עם Windows

כדי להגדיר את הדרישות למחשבים עם Windows:

  1. בתפריט הימני ב-Play Console, לוחצים על הגדלת מספר המשתמשים > נוכחות בחנות Play > הגדרות החנות (קישור ישיר).
  2. בקטע דרישות למחשב, לוחצים על עריכה בצד שמאל.
  3. מעדכנים את השדות ולוחצים על שמירה.

הגדרת הגרפיקה של רכישה באפליקציה

השלב הזה הוא אופציונלי. כדי להגדיר את הגרפיקה של רכישה באפליקציה:

  1. בתפריט הימני של Play Console, בוחרים באפשרות הגדלת מספר המשתמשים > נוכחות בחנות Play > דפי אפליקציה בחנות (קישור ישיר).
  2. בקטע דף האפליקציה בחנות שמוגדר כברירת מחדל בכרטיסייה דפי האפליקציה, לוחצים על הכפתור -> (חץ) בצד שמאל. פעולה זו תעביר אתכם אל דף האפליקציה בחנות שמוגדר כברירת מחדל.
  3. עוברים לקטע Google Play Games במחשב ומעלים את התמונה בגרפיקה של רכישה באפליקציה ב-Google Play Games במחשב (Windows).
  4. לוחצים על שמירה.

שליחת שינויים לבדיקה

  1. בתפריט הימני של Play Console, בוחרים באפשרות סקירת השינויים לפרסום.
  2. בקטע שינויים שעדיין לא נשלחו לבדיקה, לוחצים על שליחת השינויים לבדיקה.

אחרי שצוות הבדיקה יאשר את השינויים, המשחק יהיה זמין ב-Google Play.