النشر باستخدام أداة التثبيت

يوضّح لك هذا المستند كيفية نشر لعبتك على برنامج "ألعاب Google Play على الكمبيوتر" باستخدام أداة تثبيت اللعبة.

باستخدام مسار التثبيت من المطوّر، يجب أن تتولّى أداة تثبيت اللعبة التي تقدّمها إدارة عملية تثبيت اللعبة وتحديثها وإلغاء تثبيتها.

قبل البدء

ادمج حزمة تطوير البرامج (SDK) الخاصة بـ "ألعاب Google Play" في لعبتك.

تجميع لعبتك كملف WAB

يتطلّب برنامج "ألعاب Google Play على الكمبيوتر" تحميل برنامج تثبيت لعبتك إلى 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: قيمة منطقية تشير إلى ما إذا كان بإمكان أداة التثبيت قبول وسيطات سطر الأوامر لتفعيل ميزة التشغيل التلقائي. هذه السمة اختيارية والقيمة التلقائية لها هي "خطأ". لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تفعيل ميزة "التشغيل التلقائي".

      • INSTALLER_PATH: مسار ملف المثبِّت داخل WAB يمكن أن يكون هذا المسار مطلقًا أو نسبيًا بالنسبة إلى الدليل الرئيسي لإعدادات النشر على Play. على سبيل المثال، path\to\test\installer. تذكَّر استخدام authenticode وتوقيع الرمز لتوقيع ملف التثبيت التنفيذي للعبتك.

      • ‫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 على الكمبيوتر" عن هذا المسار ضمن عدة أقسام فرعية للعثور على القيم المطلوبة لتشغيل التطبيق وإلغاء تثبيته.

        يجب أن ينشئ الملف التنفيذي المحدّد في INSTALLER_PATH مفاتيح التسجيل هذه. قبل اكتمال عملية التثبيت، يجب إنشاء أزواج مفاتيح السجل وأسماء القيم المحدّدة ضمن installation-path-registry-location وlaunch-path-registry-location وuninstall-path-registry-location. على الرغم من أنّ المثال يستخدم InstallLocation وUninstallString، يمكنك تحديد أي اسم في علامات <value-name> هذه، طالما أنّ أداة التثبيت تنشئ إدخالات سجلّ مقابلة للجميع. يستخدم برنامج "ألعاب Google Play على الكمبيوتر" هاتين القيمتين لتشغيل اللعبة وإلغاء تثبيتها. إذا كانت لعبتك تستخدم مشغّلاً، يجب أن يشير هذا المسار إلى مفتاح التسجيل الذي يحتوي على معلومات التثبيت الخاصة بالمشغّل، ويجب أن تشير القيمة في إدخال التسجيل المحدّد بواسطة 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 على الكمبيوتر" تفعيل ميزة "التشغيل التلقائي" التي تشغّل لعبتك تلقائيًا فور اكتمال عملية التثبيت. توفّر هذه الميزة تجربة سلسة للمستخدم من خلال نقل اللاعب مباشرةً إلى اللعبة، مع إثبات هويته بالكامل ضمن منظومة "ألعاب Google Play على الكمبيوتر" المتكاملة.

    طريقة العمل

    عند تفعيل الميزة، ستنقل "ألعاب Google Play على الكمبيوتر" رمزًا مميزًا للجلسة إلى عملية التثبيت التابعة لجهة خارجية باستخدام وسيطات سطر الأوامر. بعد ذلك، يكون برنامج التثبيت مسؤولاً عن استخراج هذا الرمز واستخدامه لتشغيل ملف اللعبة التنفيذي في سياق مصادق عليه.

    المتطلّبات الأساسية

    لاستخدام هذه الميزة، يجب أن يكون برنامج التثبيت التابع لجهة خارجية قادرًا على التعامل مع وسيطات سطر الأوامر.

    خطوات التنفيذ

    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
      • عناوين URL التلقائية: false
      • السلوك: عند ضبطها على "صحيح"، سيضيف GPG الرمز المميز للجلسة إلى وسيطات سطر الأوامر عند تنفيذ برنامج التثبيت.

    2. التعامل مع الرمز المميز للجلسة في برنامج التثبيت

      عندما يشغّل عميل GPG برنامج التثبيت، سيتلقّى الرمز المميز للجلسة كمعلَمة سطر أوامر.

      • تنسيق الوسيطة: --g_session_token=<TOKEN>

      في ما يلي الإجراءات التي يجب اتّخاذها:

      • الاستخراج: يجب أن تحلّل أداة التثبيت وسيطات سطر الأوامر لاسترداد سلسلة الرمز المميّز.
      • نقل البيانات: إذا كان مسار التثبيت يتضمّن تشغيل مشغّل ثانوي أو عملية لعبة، تكون أداة التثبيت مسؤولة عن نقل الرمز المميز للجلسة بأمان إلى عملية اللعبة النهائية التي تستخدم حزمة تطوير البرامج (SDK).
      • التشغيل: استخدِم الرمز المميز للجلسة المقدَّم لبدء تنفيذ اللعبة. يضمن ذلك تشغيل اللعبة في سياق مصادَق عليه في "ألعاب Google Play". وفي حال عدم توفّرها، ستتعذّر عملية InitializeSDK وسيكون على اللاعب إعادة تشغيل لعبتك.

    3. معالجة الأخطاء والبدائل

      • استرداد الرمز المميز: إذا تعذّر على GPG إنشاء رمز مميز للجلسة أو تمريره لأي سبب (مثل تعذُّر إنشاء الرمز المميز)، ستستمر عملية التثبيت. ومع ذلك، سيتم تشغيل برنامج التثبيت بدون الوسيطة --g_session_token.
      • المتانة: يجب تصميم برنامج التثبيت للتعامل مع الحالات التي لا يتوفّر فيها رمز الجلسة. في مثل هذه الحالات، يجب أن يتابع برنامج التثبيت عملية التثبيت العادية، ويجب ألا يتم تشغيل اللعبة تلقائيًا لأنّ InitializeSDK سيتعذّر تنفيذه على أي حال.
      • أخطاء برنامج التثبيت: أنت المسؤول عن قوة برنامج التثبيت والتعامل مع الأخطاء وتسلسل تشغيل اللعبة الذي يبدأه. لا يمكن لأداة GPG التحكّم في العمليات التي تحدث داخل أداة التثبيت بعد تشغيلها.

نشر اللعبة باستخدام Play Console

بعد إنشاء حزمة تطبيق Android (WAB) للعبتك بنجاح، حمِّلها إلى Play Console وأدِر إعداداتها ومتطلباتها. اتّبِع الخطوات التالية لنشر لعبتك:

إضافة شكل الجهاز المخصّص لبرنامج "ألعاب Google Play على الكمبيوتر"

هذه الخطوة مطلوبة فقط عند نشر لعبة للمرة الأولى.

  1. في Play Console، اختَر الاختبار والإصدار > الإعداد > الإعدادات المتقدّمة من القائمة اليمنى (رابط مباشر).

  2. انتقِل إلى علامة التبويب أشكال الأجهزة وأضِف Google Play Games on PC من القائمة المنسدلة + إضافة شكل جهاز.

  3. انقر على الزر إدارة بجانب ألعاب Google Play على الكمبيوتر في الجهة اليسرى.

  4. ضَع علامة في المربّع بجانب الخيار استخدام قناة إصدار مخصّصة للعبتك التي تتضمّن حِزمة تطبيق Windows.

  5. انقر على حفظ، ثم انقر على حفظ مرة أخرى في مربّع حوار التأكيد.

تفعيل ميزة "النشر المُدار"

لتفعيل ميزة "النشر المُدار"، اتّبِع الخطوات التالية.

  1. في صفحة نظرة عامة على النشر، ضِمن قسم النشر المُدار، انقر على تفعيل ميزة "النشر المُدار".
  2. سيظهر مربع حوار. بدِّل إلى تفعيل ميزة "النشر المُدار" للقناة.
  3. انقر على حفظ.

تحميل ملف WAB

لتحميل ملف WAB، اتّبِع الخطوات التالية:

  1. في Play Console، اختَر الاختبار والإصدار > الإعدادات المتقدّمة من القائمة اليمنى (رابط مباشر).
  2. في صفحة الإعدادات المتقدّمة، انقر على علامة التبويب أشكال الأجهزة.
  3. في علامة التبويب أشكال الأجهزة، انقر على + إضافة شكل جهاز واختَر ألعاب Google Play على الكمبيوتر لإضافته.
  4. في قسم ألعاب Google Play على الكمبيوتر، انقر على إدارة.
  5. اختَر استخدام قناة إصدار مخصّصة للعبتك التي تتضمّن حِزمة تطبيق Windows.
  6. انقر على حفظ.
  7. في Play Console، انقر على الاختبار والإصدار > الإصدار العلني (رابط مباشر) في القائمة اليمنى.
  8. في صفحة الإنتاج، اختَر ألعاب Google Play على الكمبيوتر (لنظام التشغيل Windows) فقط من القائمة المنسدلة الخاصة بشكل الجهاز.
  9. في علامة التبويب حِزمة تطبيق Windows، انقر على تعديل وحمِّل ملف WAB.

ضبط متطلبات أجهزة كمبيوتر Windows

لضبط متطلبات أجهزة كمبيوتر Windows، اتّبِع الخطوات التالية:

  1. في Play Console، انقر على زيادة عدد المستخدمين > التوفُّر في المتجر > إعدادات المتجر (رابط مباشر) في القائمة اليمنى.
  2. في قسم متطلبات الكمبيوتر، انقر على الزر تعديل على يسار الصفحة.
  3. عدِّل الحقول وانقر على حفظ.

ضبط صورة عملية الشراء داخل التطبيق

هذه الخطوة اختيارية. لضبط صورة عملية الشراء داخل التطبيق، اتّبِع الخطوات التالية:

  1. في Play Console، انقر على زيادة عدد المستخدمين > التوفّر في المتجر > بطاقات بيانات المتجر(رابط مباشر) في القائمة اليمنى.
  2. في قسم بطاقة بيانات المتجر التلقائية ضمن علامة التبويب بطاقات البيانات، انقر على الزر -> (السهم) على الجانب الأيسر. سينقلك هذا الإجراء إلى صفحة بطاقة بيانات المتجر التلقائية.
  3. انتقِل إلى قسم ألعاب Google Play على الكمبيوتر وحمِّل الصورة في صورة لعمليات الشراء داخل التطبيق في برنامج "ألعاب Google Play على الكمبيوتر" (Windows).
  4. انقر على حفظ.

إرسال التغييرات للمراجعة

  1. في Play Console، انقر على نظرة عامة على النشر في القائمة اليمنى.
  2. في قسم التغييرات التي لم يتم إرسالها للمراجعة بعد، انقر على إرسال التغييرات للمراجعة.

بعد أن يوافق فريق المراجعة على التغييرات التي أجريتها، سيصبح بإمكان المستخدمين العثور على لعبتك على Google Play.