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

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

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

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

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

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

כדי להשתמש ב-Google Play Games במחשב, צריך להעלות את קובץ ההתקנה של המשחק ל-Google Play Console כחבילת אפליקציות ל-Windows‏ (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. מידע נוסף זמין במאמר הפעלת הפעלה אוטומטית.

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

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

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

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

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

   איך זה עובד

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

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

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

   שלבי ההטמעה

   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.