Pubblicazione gestita di Google Play

Questo documento mostra come pubblicare il tuo gioco su Google Play Games su PC utilizzando l'installazione gestita da Play.

Con l'installazione gestita da Play, Google Play gestisce l'installazione, l'aggiornamento e la disinstallazione del gioco utilizzando i file e i metadati del gioco forniti in un file Windows App Bundle (WAB).

Prima di iniziare

Integra l'SDK Google Play Games nel tuo gioco.

Creare un pacchetto del gioco come file WAB

Per creare un file WAB di installazione gestita da Play:

Scarica lo strumento di pubblicazione di Play. Puoi eseguire questo strumento nella riga di comando di Windows o in PowerShell.
Crea il file di configurazione di pubblicazione di Play con un nome a tua scelta. Ad esempio, play_publishing_config.xml con il seguente formato:
```
<?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>

  
  <game-files>
    <file-set>
      <root-folder-path>PATH_TO_ROOT_FOLDER</root-folder-path>
      
      
      <exclusions>
        <file-path>REGEX_PATTERN_OF_EXCLUDED_FILES</file-path>
        <file-path>PATH_TO_BE_EXCLUDED</file-path>
      </exclusions>

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

  
  <launch-command>
    <path>PATH_TO_LAUNCH_FILE</path>
    <arguments>ARGUMENTS</arguments>
  </launch-command>

  
  <lifecycle-operations>
    
    <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-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>
```
Sostituisci quanto segue:
- PACKAGE_NAME: il nome del pacchetto del gioco. Si tratta dell'identificatore univoco che verrà associato al tuo gioco su Google Play. Ad esempio, com.yourcompany.yourgame. Il nome del pacchetto deve rispettare le seguenti regole:
  - Deve avere almeno due segmenti (uno o più punti).
  - Ogni segmento deve iniziare con una lettera.
  - Tutti i caratteri devono essere alfanumerici o un trattino basso ([a-zA-Z0-9_]).
- VERSION_NAME: la stringa della versione del gioco. Può essere una stringa arbitraria, ma deve essere univoca per tutti i file WAB caricati per il tuo gioco. Ad esempio: 1.0, 1.0.1-beta, 2025.11.24, v1.rc1.
- PATH_TO_ROOT_FOLDER: il percorso della cartella principale contenente i file del gioco. Tutti i file in questa cartella, ad eccezione di quelli menzionati nelle esclusioni, vengono aggiunti al bundle. Questo percorso può essere assoluto o relativo alla directory contenente il file play_publishing_config.xml.
  
  Nota: ad eccezione di PATH_TO_ROOT_FOLDER, tutti i percorsi dei file specificati in questa configurazione XML possono essere relativi a PATH_TO_ROOT_FOLDER o percorsi assoluti.
- exclusions: (facoltativo) specifica i percorsi dei file o i pattern per i file all'interno di PATH_TO_ROOT_FOLDER da escludere dal bundle. Puoi includere più elementi file-path all'interno dell'elemento exclusions. Un percorso può essere rappresentato in due modi:
  - Come percorso del file: percorso del file da escludere.
  - Come stringa regex: tutti i file che corrispondono alla stringa dell'espressione regolare vengono esclusi dal bundle. Utilizza la sintazione RE2.
- file-attribute: (facoltativo) definisce gli attributi per file specifici o file che corrispondono a un pattern di espressione regolare.
  - FILE_ATTRIBUTE_VALUE: può essere uno dei seguenti valori:
    - SKIP_UPDATE: durante un aggiornamento, questo attributo indica al sistema di copiare il file solo se non è già presente, mantenendo eventuali modifiche a un file esistente.
    - MODIFIED_ON_DEVICE: utilizza questo attributo per i file che devono essere aggiornati, ma che potrebbero essere modificati sul dispositivo dopo l'installazione. Durante un aggiornamento, il sistema scarica il nuovo file completo e sovrascrive la versione installata. Se questo file è diverso dalla versione installata durante i controlli di integrità dell'installazione, l'installazione non viene considerata danneggiata.
  - file-path: identifica i file per questo attributo. Puoi includere più elementi file-path all'interno di ogni elemento file-attribute. Ogni percorso può essere rappresentato in due modi:
    - Come percorso del file: percorso del file a cui associare questo attributo.
    - Come stringa regex: tutti i file che corrispondono alla stringa dell'espressione regolare vengono associati al valore dell'attributo. Utilizza la sintazione RE2.
- PATH_TO_LAUNCH_FILE: percorso del file eseguibile utilizzato per avviare il gioco.
- ARGUMENTS: (facoltativo) argomenti della riga di comando. L'elemento <arguments> viene utilizzato per passare gli argomenti a un file eseguibile specificato in <launch-command>, <install-operation> o <uninstall-operation>. Ogni utilizzo dell'elemento <arguments> si applica solo all'eseguibile accanto al quale è definito, consentendoti di specificare argomenti diversi per eseguibili diversi.
  - Se un eseguibile ha più argomenti, separali con uno spazio.
  - Anteponi -- o - agli argomenti se l'eseguibile lo richiede. Esempio:
```
<arguments>--package_name --version_name</arguments>
```
- lifecycle-operations: (facoltativo) azioni personalizzate da eseguire durante l'installazione o la disinstallazione del gioco.
  - install-operation: un'azione da eseguire quando il gioco viene installato. Puoi specificare due tipi di operazioni di installazione: execute-file e update-registry.
  - uninstall-operation: un'azione da eseguire prima della disinstallazione del gioco. Le operazioni update-registry vengono ripristinate automaticamente durante la disinstallazione.
  - INSTALL_OPERATION_REQUIRES_ELEVATION: indica se l'operazione di installazione deve essere eseguita con privilegi di amministratore.
    - "true": esegui come amministratore.
    Avviso: mostra una richiesta UAC per il giocatore.
    - "false": esegui come utente corrente. Questo è il valore predefinito se non viene specificato.
  - UNINSTALL_OPERATION_REQUIRES_ELEVATION: indica se l'operazione di disinstallazione deve essere eseguita con privilegi di amministratore.
    - "true": esegui come amministratore.
    Avviso: mostra una richiesta UAC per il giocatore.
    - "false": esegui come utente corrente. Questo è il valore predefinito se non viene specificato.
    Nota: se un'azione <install-operation> o <uninstall-operation> include un'azione <execute-file> e imposti requiresElevation="true", allora il file eseguibile specificato in questa azione deve essere firmato utilizzando la firma Authenticode.
  - operation-identifier: una stringa univoca per identificare un'azione install-operation.
  - execute-file: esegue un file eseguibile.
    - PATH_TO_INSTALL_EXECUTE_FILE: percorso di un eseguibile da eseguire durante l'installazione.
    - PATH_TO_UNINSTALL_EXECUTE_FILE: percorso di un eseguibile da eseguire prima della disinstallazione.
  - update-registry: crea o aggiorna una voce del Registro di sistema di Windows.
    - BASE_KEY: definisce la chiave principale da utilizzare nel Registro di sistema di Windows. Valori accettati: HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_PERFORMANCE_DATA e HKEY_USERS. Quando esegui un'operazione update-registry, imposta requiresElevation="true" sull'elemento install-operation in base a baseKey utilizzato:
      - HKEY_LOCAL_MACHINE o HKEY_CURRENT_CONFIG: Imposta requiresElevation="true".
      - HKEY_CURRENT_USER: requiresElevation="true" non è necessario.
      - HKEY_CLASSES_ROOT: Imposta requiresElevation="true" solo se scrivi nelle sezioni a livello di macchina; non è necessario per le sezioni specifiche dell'utente.
      - HKEY_USERS: contiene i profili di tutti gli utenti. Imposta requiresElevation="true" quando modifichi profili diversi da quello dell'utente corrente (ad es. altri utenti o .DEFAULT).
    - SUB_KEY_PATH: rappresenta il percorso di una chiave specifica all'interno del Registro di sistema di Windows, nidificata sotto la baseKey principale.
    - VALUE_NAME: specifica il nome della voce di dati che vuoi modificare all'interno della sottochiave designata.
    - REGISTRY_VALUE_TYPE: questo attributo specifica il tipo di dati del valore scritto nel registro. I valori supportati sono STRING per una stringa o DWORD per un numero a 32 bit.
    - VALUE_TEXT: dati da archiviare nella chiave del registro.
Nota:
per includere blocchi di testo con caratteri speciali che non devono essere analizzati come markup XML, utilizza una sezione CDATA. Ad esempio:
```
<file-path><![CDATA[file path with special characters <>]]></file-path>
```
Nota: verifica che tutti i file binari del gioco che fornisci siano destinati all'esecuzione su architetture x86 o x64. I file binari per altre architetture non sono supportati.

Importante: espressioni regolari per i percorsi dei file:
Quando utilizzi le espressioni regolari per specificare i percorsi dei file (ad esempio, per esclusioni o attributi), è fondamentale utilizzare barre (/) come separatori di directory. Questo perché lo strumento normalizza internamente tutti i percorsi dei file in modo da utilizzare le barre, indipendentemente dal sistema operativo.

Le barre rovesciate (\\) devono essere utilizzate solo per il loro scopo standard nelle espressioni regolari: i caratteri di escape per i caratteri speciali.

Esempio: per escludere i file di log come test_failed1.log, test_failed2.log all'interno di una directory testing:

Corretto: testing/test_failed\d\.log
/ viene utilizzato per la directory.
\d corrisponde a qualsiasi cifra.
\. corrisponde a un punto letterale.

Non corretto: testing\\test_failed\d\.log
L'utilizzo di \\ come separatore di percorso qui entrerà in conflitto con l'interpretazione di \\t e \\d come sequenze di escape da parte di RE2, causando un comportamento imprevisto.

Per altri esempi, consulta Come utilizzare le espressioni regolari.
Come utilizzare le espressioni regolari

Puoi utilizzare le espressioni regolari della sintassi RE2 nei tag file-path per applicare esclusioni o attributi di file a un gruppo di file. Ricorda di utilizzare le barre / come separatori di directory e di utilizzare i caratteri di escape per i caratteri speciali delle espressioni regolari con una barra rovesciata \. Ad esempio, utilizza \. per trovare la corrispondenza di un punto letterale ., o \d per trovare la corrispondenza di una cifra.

Ecco alcuni esempi comuni:
- Trovare la corrispondenza di tutti i file con un'estensione specifica (ad esempio, .log) in qualsiasi directory
  Utilizza .*\.log per trovare la corrispondenza di qualsiasi percorso che termina con .log, ad esempio game.log o logs/errors.log.
  <file-path>.*\.log</file-path>
- Trovare la corrispondenza di tutti i file e le sottodirectory all'interno di una cartella specifica (ad esempio, "temp")
  Utilizza temp/.* per trovare la corrispondenza di tutti i percorsi che iniziano con temp/, ad esempio temp/data.txt o temp/saves/file.sav.
  <file-path>temp/.*</file-path>
- Trovare la corrispondenza dei file che corrispondono a un pattern in una cartella specifica
  Utilizza assets/level\d\.dat per trovare la corrispondenza di assets/level1.dat, assets/level2.dat, ma non assets/other.dat.
  <file-path>assets/level\d\.dat</file-path>
- Trovare la corrispondenza di un nome di cartella quando viene visualizzato in qualsiasi punto del percorso
  Utilizza .*/cache/.* per trovare la corrispondenza dei file in qualsiasi directory denominata cache, ad esempio game/cache/file.txt o temp/cache/other.log.
  <file-path>.*/cache/.*</file-path>
- Trovare la corrispondenza dei file con una delle diverse estensioni (ad esempio, .ini, .cfg, .sav)
  Utilizza .*\.(ini|cfg|sav) per trovare la corrispondenza di qualsiasi file che termina con .ini, .cfg o .sav, ad esempio settings.ini, config.cfg o saves/slot1.sav.
  <file-path>.*\.(ini|cfg|sav)</file-path>
- Trovare la corrispondenza dei file con un'estensione specifica in directory specifiche (ad esempio, .ogg in music/ o sfx/)
  Utilizza (music|sfx)/.*\.ogg per trovare la corrispondenza di tutti i file .ogg che si trovano nelle directory music/ o sfx/, ma non altrove. Trova la corrispondenza di music/level1.ogg o sfx/explosion.ogg, ma non voice/intro.ogg.
  <file-path>(music|sfx)/.*\.ogg</file-path>
Esempio di file di configurazione di pubblicazione di Play

Di seguito è riportato un esempio di play_publishing_config.xml per un gioco chiamato 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> 
        <file-path>deprecated_graphics</file-path> 
        <file-path>.*\.log</file-path> 
      </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> 
      </file-attribute>
    </file-set>
  </game-files>

  <launch-command>
    <path>launcher_test_game.exe</path>
    <arguments>--launch-arg</arguments> 
  </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> 
      </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> 
      </execute-file>
    </uninstall-operation>
  </lifecycle-operations>
</play-publishing-config>
```
Esegui lo strumento di pubblicazione di Play nella riga di comando di Windows o in PowerShell utilizzando il comando build-bundle:
```
playpublishingtool.exe build-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH
```
Per sovrascrivere un file WAB esistente con lo stesso nome, utilizza l'argomento --force.
```
playpublishingtool.exe build-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH --force
```
Sostituisci quanto segue:
- PLAY_PUBLISHING_CONFIG_PATH: il percorso della configurazione di pubblicazione di Play. Ad esempio, path\to\play_publishing_config.xml.
- WAB_OUTPUT_PATH: il percorso del file WAB. Ad esempio, path\to\output_bundle.wab.
Importante: il nome del file WAB in --output deve avere l'estensione .wab.

Nota: i percorsi --input e --output possono essere assoluti o relativi rispetto alla directory di lavoro corrente.
Come utilizzare lo strumento di pubblicazione di Play

Se hai playpublishingtool.exe, play_publishing_config.xml e i file del gioco in game_files/ nella directory di lavoro corrente:
```
.\
├── game_files/
├── play_publishing_config.xml
├── playpublishingtool.exe
```
Per creare pmi_bundle.wab nella stessa directory, esegui:
```
playpublishingtool.exe build-bundle --input=play_publishing_config.xml --output=pmi_bundle.wab
```
Mentre lo strumento crea il bundle, vedrai una barra di avanzamento nel terminale:
```
Building bundle: [====       ] 40%
```
Se l'operazione va a buon fine, dovresti vedere un output simile al seguente:
```
Building bundle: [===========] 100%
Successfully built the managed install bundle at pmi_bundle.wab
```
Trova il file WAB nella cartella:
```
  .\
  ├── game_files/
  ├── pmi_bundle.wab
  ├── play_publishing_config.xml
  ├── playpublishingtool.exe
```

Pubblicazione gestita di Google Play Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Creare un pacchetto del gioco come file WAB

Come utilizzare le espressioni regolari

Esempio di file di configurazione di pubblicazione di Play

Come utilizzare lo strumento di pubblicazione di Play

Pubblicazione gestita di Google Play