Chế độ Xuất bản có quản lý trên Play

Tài liệu này hướng dẫn bạn cách xuất bản trò chơi trên Google Play Games trên máy tính bằng tính năng Cài đặt do Play quản lý.

Với tính năng Cài đặt do Play quản lý, Google Play sẽ quản lý việc cài đặt, cập nhật và gỡ cài đặt trò chơi bằng cách sử dụng các tệp trò chơi và siêu dữ liệu mà bạn cung cấp trong tệp gói ứng dụng Windows (WAB).

Trước khi bắt đầu

Tích hợp Google Play Games SDK vào trò chơi của bạn.

Đóng gói trò chơi dưới dạng tệp WAB

Để tạo tệp WAB Cài đặt do Play quản lý, hãy làm theo các bước sau:

  1. Tải công cụ xuất bản trên Play xuống. Bạn có thể chạy công cụ này trên dòng lệnh Windows hoặc Powershell.

  2. Tạo tệp cấu hình phát hành trên Play bằng tên bất kỳ. Ví dụ: play_publishing_config.xml có định dạng như sau:

    <?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>

    Thay thế nội dung sau:

    • PACKAGE_NAME: Tên gói của trò chơi. Đây là giá trị nhận dạng duy nhất sẽ được liên kết với trò chơi của bạn trên Google Play. Ví dụ: com.yourcompany.yourgame. Tên gói phải tuân thủ các quy tắc sau:
      • Mã ứng dụng phải có ít nhất 2 phân đoạn (gồm một hoặc nhiều dấu chấm).
      • Mỗi phân đoạn phải bắt đầu bằng một chữ cái.
      • Tất cả ký tự phải có dạng chữ-số hoặc dấu gạch dưới ([a-zA-Z0-9_]).
    • VERSION_NAME: Chuỗi phiên bản của trò chơi. Đây có thể là một chuỗi tuỳ ý, nhưng phải là duy nhất trên tất cả các WAB đã tải lên cho trò chơi của bạn. Ví dụ: 1.0, 1.0.1-beta, 2025.11.24, v1.rc1.

    • PATH_TO_ROOT_FOLDER: Đường dẫn đến thư mục gốc chứa các tệp trò chơi của bạn. Tất cả các tệp trong thư mục này (ngoại trừ những tệp được đề cập trong danh sách loại trừ) đều được thêm vào gói. Đường dẫn này có thể là tuyệt đối hoặc tương đối so với thư mục chứa tệp play_publishing_config.xml.

    • exclusions: (Không bắt buộc) Chỉ định đường dẫn hoặc mẫu tệp cho các tệp trong PATH_TO_ROOT_FOLDER để loại trừ khỏi gói. Bạn có thể thêm nhiều phần tử file-path trong phần tử exclusions. Đường dẫn có thể được biểu thị theo một trong hai cách:

      • Là đường dẫn đến tệp: Đường dẫn đến tệp cần loại trừ.
      • Dưới dạng chuỗi biểu thức chính quy: Tất cả các tệp khớp với chuỗi biểu thức chính quy đều bị loại trừ khỏi gói. Sử dụng cú pháp RE2.

    • file-attribute: (Không bắt buộc) Xác định các thuộc tính cho các tệp cụ thể hoặc các tệp khớp với một mẫu biểu thức chính quy.

      • FILE_ATTRIBUTE_VALUE: Có thể là một trong những trạng thái sau đây:
        • SKIP_UPDATE: Trong quá trình cập nhật, thuộc tính này yêu cầu hệ thống chỉ sao chép tệp nếu tệp đó chưa có, đồng thời giữ nguyên mọi thay đổi đối với tệp hiện có.
        • MODIFIED_ON_DEVICE: Sử dụng tuỳ chọn này cho những tệp phải được cập nhật, nhưng có thể được sửa đổi trên thiết bị sau khi cài đặt. Hệ thống sẽ tải tệp mới đầy đủ xuống và ghi đè phiên bản đã cài đặt trong quá trình cập nhật. Nếu tệp này khác với phiên bản đã cài đặt trong quá trình kiểm tra tính toàn vẹn của quá trình cài đặt, thì quá trình cài đặt sẽ không được coi là bị hỏng.
      • file-path: Xác định các tệp cho thuộc tính này. Bạn có thể thêm nhiều phần tử file-path trong mỗi phần tử file-attribute. Mỗi đường dẫn có thể được biểu thị theo một trong hai cách sau:
        • Dưới dạng đường dẫn tệp: Đường dẫn đến tệp cần liên kết với thuộc tính này.
        • Dưới dạng chuỗi biểu thức chính quy: Tất cả các tệp khớp với chuỗi biểu thức chính quy đều được liên kết với giá trị thuộc tính. Sử dụng cú pháp RE2.

    • PATH_TO_LAUNCH_FILE: Đường dẫn đến tệp thực thi dùng để chạy trò chơi.

    • ARGUMENTS: (Không bắt buộc) Đối số dòng lệnh. Phần tử <arguments> được dùng để truyền các đối số đến một tệp thực thi được chỉ định trong <launch-command>, <install-operation> hoặc <uninstall-operation>. Mỗi lần sử dụng phần tử <arguments> chỉ áp dụng cho tệp thực thi mà phần tử đó được xác định cùng, cho phép bạn chỉ định các đối số khác nhau cho các tệp thực thi khác nhau.

      • Nếu một tệp thực thi có nhiều đối số, hãy phân tách các đối số đó bằng dấu cách.
      • Thêm đối số bằng -- hoặc - nếu tệp thực thi yêu cầu. Ví dụ: 
        <arguments>--package_name --version_name</arguments>

    • lifecycle-operations: (Không bắt buộc) Các thao tác tuỳ chỉnh cần thực hiện trong quá trình cài đặt hoặc gỡ cài đặt trò chơi.

      • install-operation: Một thao tác sẽ chạy khi trò chơi được cài đặt. Bạn có thể chỉ định 2 loại thao tác cài đặt: execute-file và update-registry.
      • uninstall-operation: Một thao tác sẽ chạy trước khi trò chơi bị gỡ cài đặt. Các thao tác update-registry sẽ tự động được hoàn nguyên trong quá trình gỡ cài đặt.

      • INSTALL_OPERATION_REQUIRES_ELEVATION: Cho biết liệu thao tác cài đặt có cần chạy với đặc quyền quản trị viên hay không.

        • "true": Chạy với tư cách Quản trị viên.
        • "false": Chạy với tư cách là người dùng hiện tại. Đây là giá trị mặc định nếu bạn không chỉ định.

      • UNINSTALL_OPERATION_REQUIRES_ELEVATION: Cho biết liệu thao tác gỡ cài đặt có cần chạy với đặc quyền quản trị viên hay không.

        • "true": Chạy với tư cách Quản trị viên.
        • "false": Chạy với tư cách là người dùng hiện tại. Đây là giá trị mặc định nếu bạn không chỉ định.

      • operation-identifier: Một chuỗi duy nhất để xác định install-operation.

      • execute-file: Chạy một tệp thực thi.

        • PATH_TO_INSTALL_EXECUTE_FILE: Đường dẫn đến một tệp thực thi để chạy trong quá trình cài đặt.
        • PATH_TO_UNINSTALL_EXECUTE_FILE: Đường dẫn đến một tệp thực thi để chạy trước khi gỡ cài đặt.

      • update-registry: Tạo hoặc cập nhật một mục nhập trong sổ đăng ký Windows.

        • BASE_KEY: Xác định khoá gốc sẽ được dùng trong sổ đăng ký Windows. Giá trị được chấp nhận: HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_PERFORMANCE_DATA và HKEY_USERS. Khi thực hiện thao tác update-registry, hãy đặt requiresElevation="true" trên install-operation mẹ dựa trên baseKey đã dùng:
          • HKEY_LOCAL_MACHINE hoặc HKEY_CURRENT_CONFIG: Đặt requiresElevation="true".
          • HKEY_CURRENT_USER: Không cần requiresElevation="true".
          • HKEY_CLASSES_ROOT: Chỉ đặt requiresElevation="true" nếu ghi vào các phần trên toàn bộ máy; không bắt buộc đối với các phần dành riêng cho người dùng.
          • HKEY_USERS: Chứa hồ sơ cho tất cả người dùng. Đặt requiresElevation="true" khi sửa đổi hồ sơ không phải của người dùng hiện tại (ví dụ: người dùng khác hoặc .DEFAULT).
        • SUB_KEY_PATH: Thể hiện đường dẫn đến một khoá cụ thể trong Sổ đăng ký Windows, được lồng trong baseKey chính.
        • VALUE_NAME: Tham số này chỉ định tên của mục nhập dữ liệu mà bạn muốn sửa đổi trong khoá phụ được chỉ định.
        • REGISTRY_VALUE_TYPE: Thuộc tính này chỉ định kiểu dữ liệu của giá trị đang được ghi vào sổ đăng ký. Giá trị được hỗ trợ là STRING cho chuỗi hoặc DWORD cho số 32 bit.
        • VALUE_TEXT: Dữ liệu sẽ được lưu trữ trong khoá đăng ký.

    Cách sử dụng biểu thức chính quy

    Bạn có thể sử dụng biểu thức chính quy cú pháp RE2 trong thẻ file-path để áp dụng tiêu chí loại trừ hoặc thuộc tính tệp cho một nhóm tệp. Hãy nhớ sử dụng dấu gạch chéo / làm dấu phân cách thư mục và dùng dấu gạch chéo ngược \ để thoát các ký tự đặc biệt trong biểu thức chính quy. Ví dụ: hãy dùng \. để khớp với dấu chấm theo nghĩa đen . hoặc \d để khớp với một chữ số.

    Dưới đây là một số ví dụ phổ biến:

    • Khớp tất cả tệp có đuôi cụ thể (Ví dụ: .log) trong bất kỳ thư mục nào

      Sử dụng .*\.log để khớp với mọi đường dẫn kết thúc bằng .log, chẳng hạn như game.log hoặc logs/errors.log.

      <file-path>.*\.log</file-path>
    • Khớp tất cả tệp và thư mục con trong một thư mục cụ thể (Ví dụ: "temp")

      Sử dụng temp/.* để khớp với tất cả đường dẫn bắt đầu bằng temp/, chẳng hạn như temp/data.txt hoặc temp/saves/file.sav.

      <file-path>temp/.*</file-path>
    • Khớp các tệp khớp với một mẫu trong một thư mục cụ thể

      Sử dụng assets/level\d\.dat để khớp với assets/level1.dat, assets/level2.dat nhưng không khớp với assets/other.dat.

      <file-path>assets/level\d\.dat</file-path>
    • Khớp tên thư mục khi tên đó xuất hiện ở bất kỳ vị trí nào trong đường dẫn

      Sử dụng .*/cache/.* để so khớp các tệp trong bất kỳ thư mục nào có tên là cache, chẳng hạn như game/cache/file.txt hoặc temp/cache/other.log.

      <file-path>.*/cache/.*</file-path>
    • Đối sánh các tệp có một trong số các đuôi tệp (Ví dụ: .ini, .cfg, .sav)

      Sử dụng .*\.(ini|cfg|sav) để so khớp mọi tệp có đuôi là .ini, .cfg hoặc .sav, chẳng hạn như settings.ini, config.cfg hoặc saves/slot1.sav.

      <file-path>.*\.(ini|cfg|sav)</file-path>
    • Ghép các tệp có đuôi cụ thể trong các thư mục cụ thể (Ví dụ: .ogg trong music/ hoặc sfx/)

      Sử dụng (music|sfx)/.*\.ogg để so khớp mọi tệp .ogg nằm trong thư mục music/ hoặc sfx/, nhưng không nằm ở nơi khác. Khớp với music/level1.ogg hoặc sfx/explosion.ogg, nhưng không khớp với voice/intro.ogg.

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

    Ví dụ về tệp cấu hình xuất bản trên Play

    Sau đây là một ví dụ về play_publishing_config.xml cho một trò chơi có tên là 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. Chạy công cụ xuất bản trên Play trên dòng lệnh Windows hoặc Powershell bằng lệnh build-bundle:

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

    Để ghi đè một tệp WAB hiện có có cùng tên, hãy dùng đối số --force.

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

    Thay thế nội dung sau:

    • PLAY_PUBLISHING_CONFIG_PATH: Đường dẫn đến cấu hình xuất bản trên Play. Ví dụ: path\to\play_publishing_config.xml.
    • WAB_OUTPUT_PATH: Đường dẫn đến tệp WAB. Ví dụ: path\to\output_bundle.wab.

    Cách sử dụng công cụ xuất bản của Play

    Nếu bạn có playpublishingtool.exe, play_publishing_config.xml và các tệp trò chơi của bạn trong game_files/ trong thư mục đang hoạt động hiện tại:

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

    Để tạo pmi_bundle.wab trong cùng một thư mục, hãy chạy:

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

    Trong khi công cụ này tạo gói, bạn sẽ thấy một thanh tiến trình trên thiết bị đầu cuối:

    Building bundle: [====       ] 40%

    Nếu thành công, bạn sẽ thấy kết quả tương tự như sau:

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

    Tìm tệp WAB trong thư mục:

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