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

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

من خلال ميزة "التثبيت المُدار في Play"، يدير Google Play عملية تثبيت اللعبة وتحديثها وإلغاء تثبيتها باستخدام ملفات اللعبة والبيانات الوصفية التي تقدّمها في ملف حِزمة تطبيق Windows (WAB).

قبل البدء

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

تجميع لعبتك كملف 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. يمكن تمثيل المسار بإحدى طريقتين:

     • كمسار ملف: مسار الملف المطلوب استبعاده
     • كسلسلة تعبير عادي: يتم استبعاد جميع الملفات التي تتطابق مع سلسلة التعبير العادي من الحزمة. استخدِم بنية RE2.

   • file-attribute: (اختياري) تحدّد سمات لملفات معيّنة أو ملفات تطابق نمط تعبير عادي.

     • FILE_ATTRIBUTE_VALUE: يمكن أن تكون إحدى القيم التالية:
       • ‫SKIP_UPDATE: أثناء التحديث، تخبر هذه السمة النظام بنسخ الملف فقط إذا لم يكن موجودًا من قبل، مع الحفاظ على أي تغييرات في ملف حالي.
       • MODIFIED_ON_DEVICE: استخدِم هذا الخيار للملفات التي يجب تعديلها، ولكن يمكن تعديلها على الجهاز بعد التثبيت. ينزّل النظام الملف الجديد الكامل ويستبدل الإصدار المثبَّت أثناء التحديث. إذا كان هذا الملف مختلفًا عن الإصدار المثبَّت أثناء عمليات التحقّق من سلامة التثبيت، لن يُعدّ التثبيت تالفًا.
     • file-path: تحدّد الملفات الخاصة بهذه السمة. يمكنك تضمين عناصر file-path متعددة ضمن كل عنصر file-attribute. يمكن تمثيل كل مسار بإحدى الطريقتَين التاليتَين:
       • كمسار ملف: مسار الملف الذي تريد ربط هذه السمة به
       • كسلسلة تعبير عادي: يتم ربط جميع الملفات التي تتطابق مع سلسلة التعبير العادي بقيمة السمة. استخدِم بنية 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 لمطابقة أي مسار ينتهي بـ .log، مثل game.log أو logs/errors.log.

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

   • مطابقة جميع الملفات والمجلدات الفرعية ضِمن مجلد معيّن (على سبيل المثال، temp)

     استخدِم temp/.* لمطابقة جميع المسارات التي تبدأ بـ temp/، مثل temp/data.txt أو temp/saves/file.sav.

     <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. شغِّل أداة النشر على Google 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
   

   أثناء إنشاء الحِزمة باستخدام الأداة، سيظهر شريط تقدّم في الوحدة الطرفية:

   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