انتشار نصب‌کننده

این سند به شما نشان می‌دهد که چگونه با استفاده از نصب‌کننده بازی، بازی خود را در Google Play Games روی رایانه شخصی منتشر کنید.

در جریان نصب توسط توسعه‌دهنده، نصب‌کننده بازی که شما ارائه می‌دهید باید نصب، به‌روزرسانی و حذف بازی را مدیریت کند.

قبل از اینکه شروع کنی

کیت توسعه نرم‌افزاری بازی‌های گوگل پلی را در بازی خود ادغام کنید.

بازی خود را به صورت یک فایل WAB بسته‌بندی کنید

بازی‌های گوگل پلی روی کامپیوتر نیاز دارند که نصب‌کننده بازی شما به عنوان یک فایل بسته نرم‌افزاری ویندوز (WAB) در کنسول گوگل پلی آپلود شود. برای ایجاد یک فایل WAB، این مراحل را دنبال کنید:

1. ابزار انتشار Play را دانلود کنید. می‌توانید این ابزار را در خط فرمان ویندوز یا 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 : مسیر کلید رجیستری ویندوز. این مسیر باید نسبت به یک کندوی رجیستری مانند HKEY_LOCAL_MACHINE یا HKEY_CURRENT_USER ارائه شود؛ نام کندو را در رشته مسیر وارد نکنید. برای مثال، اگر نصب‌کننده شما در HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName می‌نویسد، فقط Software\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName را مشخص کنید. بازی‌های Google Play در رایانه شخصی این مسیر را در کندوهای متعدد جستجو می‌کنند تا مقادیر مورد نیاز برای راه‌اندازی و حذف نصب را پیدا کنند.

       فایل اجرایی مشخص شده در 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 .

       اگر نصب‌کننده بازی شما یک برنامه ۳۲ بیتی است که روی ویندوز ۶۴ بیتی اجرا می‌شود، ویندوز از تغییر مسیر رجیستری برای نوشتن ورودی‌های رجیستری در مسیر 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 : نشان می‌دهد که آیا لانچر یا فایل اجرایی بازی هر بار که اجرا می‌شود، باید به عنوان Administrator اجرا شود یا خیر.

       • "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 لانچر بازی 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 را در خط فرمان ویندوز یا 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_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 روی کامپیوتر شخصی با استفاده از آرگومان‌های خط فرمان، یک توکن جلسه (session token) به فرآیند نصب‌کننده شخص ثالث (3P) شما ارسال می‌کند. سپس نصب‌کننده شما مسئول استخراج این توکن و استفاده از آن برای اجرای فایل اجرایی بازی در یک زمینه احراز هویت شده است.

   پیش‌نیازها

   برای استفاده از این ویژگی، نصاب 3P شما باید بتواند آرگومان‌های خط فرمان را مدیریت کند.

   مراحل اجرا

   1. فعال کردن پخش خودکار در پیکربندی انتشار بازی

      برای فعال کردن این ویژگی، ویژگی 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. مدیریت خطا و Fallbackها

      • بازیابی توکن: اگر به هر دلیلی، GPG نتواند توکن جلسه را تولید یا ارسال کند (مثلاً خرابی در تولید توکن)، فرآیند نصب همچنان ادامه خواهد یافت. با این حال، نصب‌کننده شما بدون آرگومان --g_session_token اجرا خواهد شد.
      • استحکام: نصب‌کننده شما باید طوری طراحی شود که سناریوهایی را که توکن جلسه وجود ندارد، مدیریت کند. در چنین مواردی، نصب‌کننده باید با نصب استاندارد ادامه دهد؛ شما نباید اجرای خودکار بازی را فعال کنید زیرا InitializeSDK در هر صورت از کار خواهد افتاد.
      • خطاهای نصب‌کننده: شما مسئول پایداری و مدیریت خطاهای نصب‌کننده و مراحل اجرای بازی هستید. GPG هیچ کنترلی بر فرآیندهایی که پس از اجرای نصب‌کننده در آن رخ می‌دهند، ندارد.

بازی را با استفاده از کنسول Play منتشر کنید

بعد از اینکه با موفقیت WAB بازی خود را ایجاد کردید، آن را در Play Console آپلود کنید و تنظیمات و الزامات آن را مدیریت کنید. برای انتشار بازی خود، مراحل زیر را دنبال کنید:

بازی های گوگل پلی را به فرم فاکتور کامپیوتر اضافه کنید

این مرحله فقط برای اولین باری که بازی را منتشر می‌کنید، لازم است.

1. در کنسول بازی در منوی سمت چپ، گزینه Test and release > Setup > Advanced settings ( لینک مستقیم ) را انتخاب کنید.

2. به برگه «فاکتورهای فرم» بروید و از منوی کشویی «افزودن فاکتور فرم» (+) Google Play Games on PC را اضافه کنید.

3. روی دکمه مدیریت مربوط به فرم فاکتور Google Play Games on PC در سمت راست کلیک کنید.

4. گزینه « استفاده از یک مسیر اختصاصی برای بازی بسته نرم‌افزاری ویندوز» را انتخاب کنید.

5. روی ذخیره کلیک کنید و سپس دوباره در کادر تأیید، ذخیره را انجام دهید .

فعال کردن انتشار مدیریت‌شده

برای فعال کردن انتشار مدیریت‌شده، این مراحل را دنبال کنید.

1. در صفحه مرور کلی انتشارات ، در بخش انتشارات مدیریت‌شده ، روی «فعال کردن انتشارات مدیریت‌شده» کلیک کنید.
2. یک کادر محاوره‌ای ظاهر می‌شود. برای آهنگ، گزینه انتشار مدیریت‌شده را فعال کنید.
3. روی ذخیره کلیک کنید.

فایل WAB را آپلود کنید

برای آپلود فایل WAB، مراحل زیر را دنبال کنید:

1. در کنسول بازی در منوی سمت چپ، گزینه Test and release > Advanced settings ( لینک مستقیم ) را انتخاب کنید.
2. در صفحه تنظیمات پیشرفته ، روی تب Form factors کلیک کنید.
3. در تب Form factors ، روی + Add form factor کلیک کنید و Google Play Games on PC را برای افزودن انتخاب کنید.
4. در بخش «بازی‌های گوگل پلی روی کامپیوتر» ، روی «مدیریت» کلیک کنید.
5. گزینه «استفاده از یک مسیر اختصاصی برای بازی بسته نرم‌افزاری ویندوز» را انتخاب کنید.
6. روی ذخیره کلیک کنید.
7. در کنسول بازی در منوی سمت چپ، گزینه Test and release > Production ( لینک مستقیم ) را انتخاب کنید.
8. در صفحه تولید ، از منوی کشویی مربوط به فرم فاکتور، گزینه «فقط بازی‌های گوگل پلی روی کامپیوتر (ویندوز)» را انتخاب کنید.
9. در برگه بسته نرم‌افزاری ویندوز ، روی ویرایش کلیک کنید و فایل WAB را آپلود کنید.

پیکربندی الزامات کامپیوتر ویندوزی

برای پیکربندی الزامات رایانه شخصی ویندوز:

1. در کنسول Play در منوی سمت چپ، گزینه‌ی «افزایش کاربران» > «حضور در فروشگاه» > «تنظیمات فروشگاه » ( لینک مستقیم ) را انتخاب کنید.
2. در بخش نیازمندی‌های رایانه شخصی ، روی دکمه ویرایش در سمت راست کلیک کنید.
3. فیلدها را به‌روزرسانی کنید و روی ذخیره کلیک کنید.

پیکربندی نمودار خرید درون‌برنامه‌ای

این یک مرحله اختیاری است. برای پیکربندی گرافیک خرید درون‌برنامه‌ای:

1. در کنسول Play در منوی سمت چپ، گزینه‌ی «افزایش کاربران > حضور در فروشگاه > فهرست فروشگاه‌ها » ( لینک مستقیم ) را انتخاب کنید.
2. در بخش فهرست فروشگاه‌های پیش‌فرض در تب فهرست‌ها ، روی دکمه -> (فلش) در سمت راست کلیک کنید. این شما را به صفحه فهرست فروشگاه‌های پیش‌فرض می‌برد.
3. به بخش بازی‌های گوگل پلی روی کامپیوتر بروید و تصویر را در قسمت «گرافیک خرید درون‌برنامه‌ای بازی‌های گوگل پلی روی کامپیوتر (ویندوز)» آپلود کنید.
4. روی ذخیره کلیک کنید.

ارسال تغییرات برای بررسی

1. در کنسول Play در منوی سمت چپ، نمای کلی انتشار را انتخاب کنید.
2. در بخش «تغییرات هنوز برای بررسی ارسال نشده‌اند» ، روی «ارسال تغییرات برای بررسی» کلیک کنید.

وقتی تیم بررسی تغییرات شما را تأیید کرد، بازی شما در گوگل پلی قابل مشاهده خواهد بود.