פרסום מנוהל ב-Play

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

בעזרת התקנה מנוהלת ב-Play,‏ Google Play מנהל את ההתקנה, העדכון וההסרה של המשחק באמצעות קובצי המשחק והמטא-נתונים שאתם מספקים בקובץ חבילת אפליקציות ל-Windows‏ (WAB).

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

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

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

כדי ליצור קובץ WAB של התקנה מנוהלת ב-Play:

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

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

   <?xml version="1.0" encoding="UTF-8"?>
   <play-publishing-config version="1.0">
     <!-- Application metadata: This section contains basic information about your game. -->
     <application>
       <package-name>PACKAGE_NAME</package-name>
       <version-name>VERSION_NAME</version-name>
     </application>
   
     <!-- Game files: This section specifies which game files to include in the bundle and how to treat them. -->
     <game-files>
       <file-set>
         <root-folder-path>PATH_TO_ROOT_FOLDER</root-folder-path>
         <!-- absolute or relative to the parent directory of the config xml -->
         <!-- Exclusions: A list of files or folders to exclude from the bundle.
              This is useful for removing development files, temporary data, or redundant assets. -->
         <exclusions>
           <file-path>REGEX_PATTERN_OF_EXCLUDED_FILES</file-path>
           <file-path>PATH_TO_BE_EXCLUDED</file-path>
         </exclusions>
   
         <!-- File attributes: Define special handling for certain files during installation and updates. -->
         <file-attribute value=FILE_ATTRIBUTE_VALUE>
           <file-path>PATH_TO_FILE</file-path>
           <file-path>REGEX_PATTERN_OF_FILE_ATTRIBUTE_FILES</file-path>
         </file-attribute>
       </file-set>
     </game-files>
   
     <!-- This file represents the startup process for this game. Google Play Games for PC should start
         this process when user clicks on "Play" on this game. -->
     <launch-command>
       <path>PATH_TO_LAUNCH_FILE</path>
       <arguments>ARGUMENTS</arguments>
     </launch-command>
   
     <!-- Lifecycle operations: Custom actions to be performed during the game's installation and uninstallation. -->
     <lifecycle-operations>
       <!-- Install operations: These actions run when the game is installed. 'requiresElevation="true"'
           will trigger a UAC prompt for administrator rights. There are three types of install
           operations that can be specified. An instance of each is listed below. -->
       <install-operation requiresElevation=INSTALL_OPERATION_REQUIRES_ELEVATION>
         <operation-identifier>OPERATION_IDENTIFIER_STRING</operation-identifier>
         <execute-file>
           <path>PATH_TO_INSTALL_EXECUTE_FILE</path>
           <arguments>ARGUMENTS</arguments>
         </execute-file>
       </install-operation>
   
       <install-operation requiresElevation=INSTALL_OPERATION_REQUIRES_ELEVATION>
         <operation-identifier>OPERATION_IDENTIFIER_STRING</operation-identifier>
         <update-registry baseKey=BASE_KEY>
           <sub-key>SUB_KEY_PATH</sub-key>
           <value-name>VALUE_NAME</value-name>
           <value type=REGISTRY_VALUE_TYPE>VALUE_TEXT</value>
         </update-registry>
       </install-operation>
   
       <!-- Uninstall operations: These actions run before the game is uninstalled. -->
       <uninstall-operation requiresElevation=UNINSTALL_OPERATION_REQUIRES_ELEVATION>
         <execute-file>
           <path>PATH_TO_UNINSTALL_EXECUTE_FILE</path>
           <arguments>ARGUMENTS</arguments>
         </execute-file>
       </uninstall-operation>
     </lifecycle-operations>
   </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.

   • ‫PATH_TO_ROOT_FOLDER: הנתיב לתיקיית הבסיס שמכילה את קובצי המשחק. כל הקבצים בתיקייה הזו, מלבד אלה שמוזכרים בהחרגות, מתווספים לחבילה. הנתיב יכול להיות מוחלט או יחסי לספרייה שמכילה את קובץ play_publishing_config.xml.

   • ‫exclusions: (אופציונלי) מציין נתיבי קבצים או תבניות של קבצים בתוך PATH_TO_ROOT_FOLDER שצריך להחריג מהחבילה. אפשר לכלול כמה רכיבי file-path בתוך רכיב exclusions. אפשר לייצג נתיב באחת משתי דרכים:

     • כנתיב קובץ: הנתיב לקובץ שרוצים להחריג.
     • כמחרוזת regex: כל הקבצים שתואמים למחרוזת הביטוי הרגולרי לא נכללים בחבילה. משתמשים בתחביר RE2.

   • ‫file-attribute: (אופציונלי) הגדרת מאפיינים לקבצים ספציפיים או לקבצים שתואמים לתבנית של ביטוי רגולרי.

     • FILE_ATTRIBUTE_VALUE: יכול להיות אחת מהאפשרויות הבאות:
       • ‫SKIP_UPDATE: במהלך עדכון, המאפיין הזה מציין למערכת להעתיק את הקובץ רק אם הוא לא קיים כבר, וכך לשמור את השינויים שבוצעו בקובץ קיים.
       • ‫MODIFIED_ON_DEVICE: משתמשים באפשרות הזו לקבצים שצריך לעדכן, אבל אפשר לשנות במכשיר אחרי ההתקנה. במהלך עדכון, המערכת מורידה את הקובץ החדש המלא ומחליפה את הגרסה המותקנת. אם הקובץ הזה שונה מהגרסה המותקנת במהלך בדיקות תקינות ההתקנה, ההתקנה לא נחשבת פגומה.
     • ‫file-path: מזהה את הקבצים של המאפיין הזה. אפשר לכלול כמה רכיבי file-path בכל רכיב file-attribute. כל נתיב יכול להיות מיוצג באחת משתי דרכים:
       • כנתיב לקובץ: הנתיב לקובץ שאליו רוצים לשייך את המאפיין הזה.
       • כמחרוזת regex: כל הקבצים שתואמים למחרוזת הביטוי הרגולרי משויכים לערך המאפיין. משתמשים בתחביר RE2.

   • ‫PATH_TO_LAUNCH_FILE: הנתיב לקובץ ההפעלה שמשמש להפעלת המשחק.

   • ‫ARGUMENTS: (אופציונלי) ארגומנטים בשורת הפקודה. הרכיב <arguments> משמש להעברת ארגומנטים לקובץ הפעלה שצוין ב-<launch-command>,‏ <install-operation> או <uninstall-operation>. כל שימוש ברכיב <arguments> חל רק על הקובץ הניתן להפעלה שהוא מוגדר לצדו, וכך אפשר לציין ארגומנטים שונים לקבצים שונים שניתנים להפעלה.

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

       <arguments>--package_name --version_name</arguments>

   • ‫lifecycle-operations: (אופציונלי) פעולות מותאמות אישית לביצוע במהלך התקנה או הסרה של משחק.

     • ‫install-operation: פעולה להרצה כשהמשחק מותקן. אפשר לציין שני סוגים של פעולות התקנה: execute-file ו-update-registry.
     • ‫uninstall-operation: פעולה להרצה לפני הסרת המשחק. פעולות update-registry מבוטלות אוטומטית במהלך ההסרה.

     • INSTALL_OPERATION_REQUIRES_ELEVATION: מציין אם פעולת ההתקנה צריכה לפעול עם הרשאות אדמין.

       • ‫true: הפעלה כמנהל.
       • ‫false: הרצה כמשתמש הנוכחי. זו ברירת המחדל אם לא צוין ערך.

     • ‫UNINSTALL_OPERATION_REQUIRES_ELEVATION: מציין אם פעולת ההסרה צריכה לפעול עם הרשאות אדמין.

       • ‫true: הפעלה כמנהל.
       • ‫false: הרצה כמשתמש הנוכחי. זו ברירת המחדל אם לא צוין ערך.

     • ‫operation-identifier: מחרוזת ייחודית לזיהוי install-operation.

     • ‫execute-file: מפעיל קובץ הפעלה.

       • ‫PATH_TO_INSTALL_EXECUTE_FILE: הנתיב לקובץ הפעלה שיופעל במהלך ההתקנה.
       • ‫PATH_TO_UNINSTALL_EXECUTE_FILE: הנתיב לקובץ הפעלה שיופעל לפני הסרת ההתקנה.

     • ‫update-registry: יוצר או מעדכן רשומה במאגר Windows.

       • ‫BASE_KEY: מגדיר את מפתח הבסיס שישמש ברישום של Windows. ערכים קבילים: HKEY_CLASSES_ROOT,‏ HKEY_CURRENT_CONFIG,‏ HKEY_CURRENT_USER,‏ HKEY_LOCAL_MACHINE,‏ HKEY_PERFORMANCE_DATA ו-HKEY_USERS. כשמבצעים פעולת update-registry, צריך להגדיר את requiresElevation="true" ברכיב ההורה install-operation בהתאם ל-baseKey שבו משתמשים:
         • ‫HKEY_LOCAL_MACHINE או HKEY_CURRENT_CONFIG: מגדירים את requiresElevation="true".
         • HKEY_CURRENT_USER: אין צורך ב-requiresElevation="true".
         • ‫HKEY_CLASSES_ROOT: מגדירים את requiresElevation="true" רק אם כותבים לקטעים ברמת המכונה. אין צורך להגדיר אותו לקטעים ספציפיים למשתמש.
         • ‫HKEY_USERS: מכיל פרופילים של כל המשתמשים. הגדרת requiresElevation="true" כשמשנים פרופילים שאינם הפרופיל של המשתמש הנוכחי (למשל, משתמשים אחרים או .DEFAULT).
       • ‫SUB_KEY_PATH: הנתיב למפתח ספציפי במאגר הנתונים של Windows, שמוטמע מתחת למפתח הראשי baseKey.
       • ‫VALUE_NAME: השם של רשומת הנתונים שרוצים לשנות במפתח המשנה שצוין.
       • ‫REGISTRY_VALUE_TYPE: המאפיין הזה מציין את סוג הנתונים של הערך שנכתב במאגר. הערכים הנתמכים הם STRING למחרוזת או DWORD למספר של 32 ביט.
       • ‫VALUE_TEXT: הנתונים שייאוחסנו במפתח הרישום.

   איך משתמשים בביטויים רגולריים

   אתם יכולים להשתמש בביטויים רגולריים עם תחביר RE2 בתגי file-path כדי להחיל החרגות או מאפייני קובץ על קבוצת קבצים. חשוב לזכור להשתמש בלוכסן / כדי להפריד בין ספריות, ולהוסיף קו נטוי הפוך \ לפני תווים מיוחדים של ביטויים רגולריים. לדוגמה, משתמשים ב-\. כדי להתאים לנקודה ., או ב-\d כדי להתאים לספרה.

   ריכזנו כאן כמה דוגמאות נפוצות:

   • התאמה של כל הקבצים עם סיומת ספציפית (לדוגמה, ‎.log) בכל ספרייה

     כדי להתאים לכל נתיב שמסתיים ב-.log, כמו game.log או logs/errors.log, משתמשים ב-.*\.log.

     <file-path>.*\.log</file-path>

   • התאמה של כל הקבצים ותיקיות המשנה בתיקייה ספציפית (לדוגמה, temp)

     כדי להתאים את כל הנתיבים שמתחילים ב-temp/, כמו temp/data.txt או temp/saves/file.sav, משתמשים ב-temp/.*.

     <file-path>temp/.*</file-path>

   • התאמת קבצים שתואמים לתבנית בתיקייה ספציפית

     משתמשים ב-assets/level\d\.dat כדי להתאים ל-assets/level1.dat ול-assets/level2.dat, אבל לא ל-assets/other.dat.

     <file-path>assets/level\d\.dat</file-path>

   • התאמה של שם תיקייה כשהוא מופיע בכל מקום בנתיב

     משתמשים ב-.*/cache/.* כדי להתאים קבצים בכל ספרייה בשם cache, כמו game/cache/file.txt או temp/cache/other.log.

     <file-path>.*/cache/.*</file-path>

   • התאמת קבצים עם אחת מכמה סיומות (לדוגמה, ‎.ini,‏ ‎.cfg,‏ ‎.sav)

     אפשר להשתמש ב-.*\.(ini|cfg|sav) כדי להתאים לכל קובץ שמסתיים ב-.ini, ב-.cfg או ב-.sav, כמו settings.ini, config.cfg או saves/slot1.sav.

     <file-path>.*\.(ini|cfg|sav)</file-path>

   • התאמת קבצים עם סיומת ספציפית בספריות ספציפיות (לדוגמה, ‎.ogg ב-music/ ‎ או ב-sfx/)

     משתמשים ב-(music|sfx)/.*\.ogg כדי להתאים לכל הקבצים .ogg שנמצאים בספריות music/ או sfx/, אבל לא במקומות אחרים. תואם ל-music/level1.ogg או ל-sfx/explosion.ogg, אבל לא ל-voice/intro.ogg.

     <file-path>(music|sfx)/.*\.ogg</file-path>

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

   דוגמה play_publishing_config.xml למשחק שנקרא TestGame:

   <?xml version="1.0" encoding="UTF-8"?>
   <play-publishing-config version="1.0">
     <application>
       <package-name>com.test.package</package-name>
       <version-name>1.0</version-name>
     </application>
   
     <game-files>
       <file-set>
         <root-folder-path>C:\Users\Username\game-files</root-folder-path>
         <exclusions>
           <file-path>mock_game\d\.exe</file-path> <!-- exclude files using a regex -->
           <file-path>deprecated_graphics</file-path> <!-- exclude a folder -->
           <file-path>.*\.log</file-path> <!-- recursively exclude all files with .log extension -->
         </exclusions>
   
         <file-attribute value="SKIP_UPDATE">
           <file-path>settings.ini</file-path>
         </file-attribute>
   
         <file-attribute value="MODIFIED_ON_DEVICE">
           <file-path>game_assets\d\.zip</file-path> <!-- define the path using regex -->
         </file-attribute>
       </file-set>
     </game-files>
   
     <launch-command>
       <path>launcher_test_game.exe</path>
       <arguments>--launch-arg</arguments> <!-- optional -->
     </launch-command>
   
     <lifecycle-operations>
       <install-operation requiresElevation="true">
         <operation-identifier>elevated-execute-file</operation-identifier>
         <execute-file>
           <path>install_file.exe</path>
           <arguments>--arg</arguments> <!-- optional -->
         </execute-file>
       </install-operation>
   
       <install-operation requiresElevation="true">
         <operation-identifier>elevated-update-registry</operation-identifier>
         <update-registry baseKey="HKEY_LOCAL_MACHINE">
           <sub-key>SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\TestGame</sub-key>
           <value-name>InstallLocation</value-name>
           <value type="STRING">C:\Program Files\TestGame</value>
         </update-registry>
       </install-operation>
   
       <uninstall-operation requiresElevation="true">
         <execute-file>
           <path>uninstall.exe</path>
           <arguments>--test-arg</arguments> <!-- optional -->
         </execute-file>
       </uninstall-operation>
     </lifecycle-operations>
   </play-publishing-config>

3. מריצים את כלי הפרסום ב-Play בשורת הפקודה של Windows או ב-PowerShell, באמצעות הפקודה build-bundle:

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

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

   playpublishingtool.exe build-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

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

   .\
   ├── game_files/
   ├── play_publishing_config.xml
   ├── playpublishingtool.exe
   

   כדי ליצור את pmi_bundle.wab באותה ספרייה, מריצים את הפקודה:

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

   בזמן שהכלי יוצר את החבילה, מוצג סרגל התקדמות ב-Terminal:

   Building bundle: [====       ] 40%
   

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

   Building bundle: [===========] 100%
   Successfully built the managed install bundle at pmi_bundle.wab
   

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

     .\
     ├── game_files/
     ├── pmi_bundle.wab
     ├── play_publishing_config.xml
     ├── playpublishingtool.exe