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

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

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

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

      الإجراءات الإلزامية:

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

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

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

بعد إنشاء حزمة تطبيق Android بنجاح للعبتك، حمِّلها إلى 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.