Pubblicazione del programma di installazione

Questo documento mostra come pubblicare il tuo gioco su Google Play Games su PC utilizzando il programma di installazione del gioco.

Con il flusso di installazione dello sviluppatore, il programma di installazione del gioco che fornisci deve gestire l'installazione, l'aggiornamento e la disinstallazione del gioco.

Prima di iniziare

Integra l'SDK Google Play Games nel tuo gioco.

Pacchettizzare il gioco come file WAB

Google Play Games su PC richiede che il programma di installazione del gioco venga caricato su Google Play Console come file app bundle per Windows (WAB). Per creare un file WAB, segui questi passaggi:

  1. Scarica lo strumento di pubblicazione di Play. Puoi eseguire questo strumento nella riga di comando di Windows o in PowerShell.

  2. Crea il file di configurazione della pubblicazione su Play, con qualsiasi nome. 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>
  <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>

    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 gioco. Ad esempio: 1.0, 1.0.1-beta, 2025.11.24, v1.rc1.

      • INSTALLER_REQUIRES_ELEVATION: indica se il file eseguibile del programma di installazione deve essere eseguito come amministratore per completare la procedura di installazione.

        • "true": esegui il file eseguibile come amministratore.
        • "false": esegui il file eseguibile come utente corrente.

      • ACCEPTS_COMMAND_LINE_ARGUMENTS: un valore booleano che indica se il programma di installazione può accettare argomenti della riga di comando per attivare la funzionalità di riproduzione automatica. Questo è facoltativo e il valore predefinito è false. Per saperne di più, consulta Attivare la riproduzione automatica.

      • INSTALLER_PATH: il percorso del file del programma di installazione all'interno del file WAB. Questo percorso può essere assoluto o relativo alla directory principale della configurazione della pubblicazione su Play. Ad esempio, path\to\test\installer. Ricorda di utilizzare Authenticode e la firma del codice per firmare il file eseguibile del programma di installazione del gioco.

      • UNIQUE_REGISTRY_PATH: il percorso della chiave del Registro di sistema di Windows. Questo percorso deve essere fornito in relazione a un hive del Registro di sistema, ad esempio HKEY_LOCAL_MACHINE o HKEY_CURRENT_USER; non includere il nome dell'hive nella stringa del percorso. Ad esempio, se il programma di installazione scrive in HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName, specifica solo Software\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName. Google Play Games su PC cerca questo percorso in più hive per individuare i valori necessari per l'avvio e la disinstallazione.

        Il file eseguibile specificato in INSTALLER_PATH deve creare queste chiavi del Registro di sistema. Prima del completamento dell'installazione, devono essere create queste coppie di chiavi e nomi di valori del Registro di sistema specificate in installation-path-registry-location, launch-path-registry-location e uninstall-path-registry-location. Sebbene l'esempio utilizzi InstallLocation e UninstallString, puoi specificare qualsiasi nome in questi tag <value-name>, a condizione che il programma di installazione crei le voci del Registro di sistema corrispondenti per tutti e tre. Google Play Games su PC utilizza questi valori per avviare e disinstallare il gioco. Se il gioco utilizza un launcher, questo percorso deve rimandare alla chiave del Registro di sistema contenente le informazioni di installazione del launcher e il valore nella voce del Registro di sistema specificata da launch-path-registry-location deve rimandare alla directory del launcher.

        Questo percorso deve essere univoco sul computer dell'utente. Ad esempio: SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName.

        Se il programma di installazione del gioco è un'applicazione a 32 bit in esecuzione su Windows a 64 bit, Windows utilizza il reindirizzamento del Registro di sistema per scrivere le voci del Registro di sistema in HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node. Ad esempio, una scrittura in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName viene reindirizzata a HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\YourUniqueName.

      • LAUNCHER_REQUIRES_ELEVATION: indica se il file eseguibile del launcher o del gioco deve essere eseguito come amministratore ogni volta che viene avviato.

        • "true": esegui il file eseguibile come amministratore.
        • "false": esegui il file eseguibile come utente corrente.

      • RELATIVE_PATH_TO_LAUNCHER_EXE: il percorso del file eseguibile del launcher o del gioco all'interno della directory di installazione. Deve includere il nome del file eseguibile del launcher o del gioco. Ad esempio, se il file del launcher o del gioco si chiama mygame.exe e si trova in {INSTALL_DIR}\Resources\mygame.exe, devi inserire Resources\mygame.exe

      • LAUNCHER_ARGS_IF_ANY: eventuali argomenti della riga di comando da passare al launcher o al gioco. Questa voce è facoltativa.

        • Nel caso di più argomenti associati a un file eseguibile, devono essere separati da uno spazio.
        • Gli argomenti devono essere preceduti da "--" o "-", se richiesto dal file eseguibile.

      • UNINSTALLER_REQUIRES_ELEVATION: indica se il file eseguibile del programma di disinstallazione deve essere eseguito come amministratore per completare la procedura di disinstallazione.

        • "true": esegui il file eseguibile come amministratore.
        • "false": esegui il file eseguibile come utente corrente.

    Esempio di file di configurazione della pubblicazione su Play

    Considera un gioco chiamato MyGame, con il programma di installazione del gioco game_installer.exe e il launcher del gioco launcher.exe. L'esempio mostra anche come utilizzare CDATA. Di seguito è riportato l'aspetto di 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. Esegui lo strumento di pubblicazione su Play nella riga di comando di Windows o in PowerShell.

    playpublishingtool.exe build-installer-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-installer-bundle --input=PLAY_PUBLISHING_CONFIG_PATH --output=WAB_OUTPUT_PATH --force

    Sostituisci quanto segue:

    • PLAY_PUBLISHING_CONFIG_PATH: il percorso della configurazione della pubblicazione su Play. Ad esempio, path\to\play_publishing_config.xml.
    • WAB_OUTPUT_PATH: il percorso del file WAB. Ad esempio, path\to\output_bundle.wab.

    Come utilizzare lo strumento di pubblicazione su Play

    Supponiamo che nella directory di lavoro corrente siano presenti il file binario dello strumento di pubblicazione su Play playpublishingtool.exe, la configurazione della pubblicazione su Play play_publishing_config.xml e il programma di installazione del gioco game_installer.exe.

    La directory di lavoro corrente dovrebbe avere il seguente aspetto:

    .\
├── game_installer.exe
├── play_publishing_config.xml
├── playpublishingtool.exe

    Per creare un file WAB con il nome, ad esempio, installer_bundle.wab nella stessa directory, il comando sarà simile al seguente:

    playpublishingtool.exe build-installer-bundle --input=play_publishing_config.xml --output=installer_bundle.wab

    Con l'argomento --force, il comando sarà simile al seguente:

    playpublishingtool.exe build-installer-bundle --input=play_publishing_config.xml --output=installer_bundle.wab --force

    Se l'operazione va a buon fine, dovresti vedere un output simile al seguente:

    Successfully built the installer bundle at installer_bundle.wab

    Trova il file WAB nella cartella:

      .\
  ├── game_installer.exe
  ├── installer_bundle.wab
  ├── play_publishing_config.xml
  ├── playpublishingtool.exe

    (Facoltativo) Attivare la riproduzione automatica dopo l'installazione dei giochi nativi per PC

    Google Play Games su PC ti consente di attivare una funzionalità di "riproduzione automatica", che avvia automaticamente il gioco immediatamente dopo il completamento della procedura di installazione. Questa funzionalità offre un'esperienza utente senza interruzioni, in quanto il giocatore viene indirizzato direttamente al gioco, completamente autenticato all'interno dell'ecosistema di Google Play Games su PC.

    Come funziona

    Quando attivi la funzionalità, Google Play Games su PC passerà un token di sessione alla procedura di installazione di terze parti (3P) utilizzando gli argomenti della riga di comando. Il programma di installazione è quindi responsabile dell'estrazione di questo token e del suo utilizzo per avviare il file eseguibile del gioco in un contesto autenticato.

    Prerequisiti

    Per utilizzare questa funzionalità, il programma di installazione di terze parti deve essere in grado di gestire gli argomenti della riga di comando.

    Procedura di implementazione

    1. Attivare la riproduzione automatica nella configurazione della pubblicazione su Play

      Per attivare questa funzionalità, aggiungi l'attributo acceptsCommandLineArguments all'elemento <installer> in play_publishing_config.xml.

      Esempio di estratto dai contenuti di 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>
      • Attributo: acceptsCommandLineArguments
      • Tipo: Boolean
      • Valore predefinito: false
      • Comportamento: se lo imposti su true, GPG aggiungerà il token di sessione agli argomenti della riga di comando durante l'esecuzione del programma di installazione.

    2. Gestire il token di sessione nel programma di installazione

      Quando il programma di installazione viene avviato dal client GPG, riceverà il token di sessione come argomento della riga di comando.

      • Formato dell'argomento: --g_session_token=<TOKEN>

      Cosa devi fare:

      • Estrazione: il programma di installazione deve analizzare gli argomenti della riga di comando per recuperare la stringa del token.
      • Propagazione: se il flusso di installazione prevede l'avvio di un launcher o di un processo di gioco secondario, il programma di installazione è responsabile del passaggio sicuro del token di sessione al processo di gioco finale che utilizza l'SDK.
      • Avvio: utilizza il token di sessione fornito per avviare il file eseguibile del gioco. In questo modo, il gioco viene eseguito in un contesto GPG autenticato. In caso contrario, InitializeSDK non andrà a buon fine e il giocatore dovrà riavviare il gioco.

    3. Gestione degli errori e fallback

      • Recupero del token: se, per qualsiasi motivo, GPG non è in grado di generare o passare un token di sessione (ad es. errore di generazione del token), la procedura di installazione continuerà comunque. Tuttavia, il programma di installazione verrà avviato senza l'argomento --g_session_token.
      • Robustezza: il programma di installazione deve essere progettato per gestire gli scenari in cui il token di sessione è assente. In questi casi, il programma di installazione deve procedere con un'installazione standard; non devi attivare l'avvio automatico del gioco perché InitializeSDK non andrà a buon fine.
      • Errori del programma di installazione: hai la responsabilità della robustezza e della gestione degli errori del programma di installazione e della sequenza di avvio del gioco che avvia. GPG non ha il controllo sui processi che si verificano all'interno del programma di installazione dopo l'avvio.

Pubblicare il gioco utilizzando Play Console

Dopo aver creato correttamente il file WAB per il gioco, caricalo su Play Console e gestisci le relative impostazioni e i requisiti. Segui i passaggi per pubblicare il gioco:

Aggiungere il fattore di forma di Google Play Games su PC

Questo passaggio è necessario solo la prima volta che pubblichi un gioco.

  1. In Play Console, nel menu a sinistra, seleziona Test e release > Configurazione > Impostazioni avanzate (link diretto).

  2. Vai alla scheda Fattori di forma e aggiungi Google Play Games on PC dal menu a discesa + Aggiungi fattore di forma.

  3. Fai clic sul pulsante Gestisci corrispondente al fattore di forma Google Play Games su PC sul lato destro.

  4. Seleziona l'opzione Utilizza un canale dedicato per il tuo gioco in app bundle per Windows.

  5. Fai clic su Salva e poi di nuovo su Salva nella finestra di dialogo di conferma.

Attivare la pubblicazione gestita

Per attivare la pubblicazione gestita, segui questi passaggi.

  1. Nella pagina Panoramica della pubblicazione, nella sezione Pubblicazione gestita, fai clic su Attiva pubblicazione gestita.
  2. Viene visualizzata una finestra di dialogo. Passa a Pubblicazione gestita attiva per il canale.
  3. Fai clic su Salva.

Caricare il file WAB

Per caricare il file WAB, segui questi passaggi:

  1. In Play Console, nel menu a sinistra, seleziona Test e release > Impostazioni avanzate (link diretto).
  2. Nella pagina Impostazioni avanzate, fai clic sulla scheda Fattori di forma.
  3. Nella scheda Fattori di forma, fai clic su + Aggiungi fattore di forma e seleziona Google Play Games su PC da aggiungere.
  4. Nella sezione Google Play Games su PC, fai clic su Gestisci.
  5. Seleziona Utilizza un canale dedicato per il tuo gioco in app bundle per Windows.
  6. Fai clic su Salva.
  7. In Play Console, nel menu a sinistra, seleziona Test e release > Produzione (link diretto).
  8. Nella pagina Produzione, seleziona Solo Google Play Games su PC (Windows) dal menu a discesa del fattore di forma.
  9. Nella scheda App bundle per Windows, fai clic su Modifica e carica il file WAB.

Configurare i requisiti di Windows PC

Per configurare i requisiti di Windows PC:

  1. In Play Console, nel menu a sinistra, seleziona Aumenta la base utenti > Presenza nello Store > Impostazioni dello store (link diretto).
  2. Nella sezione Requisiti del PC, fai clic sul pulsante Modifica sul lato destro.
  3. Aggiorna i campi e fai clic su Salva.

Configurare l'immagine in primo piano per l'acquisto in-app

Questo passaggio è facoltativo. Per configurare l'immagine in primo piano per l'acquisto in-app:

  1. In Play Console, nel menu a sinistra, seleziona Aumenta la base utenti > Presenza nello Store > Schede dello Store(link diretto).
  2. Nella sezione Scheda dello Store predefinita della scheda Schede, fai clic sul pulsante -> (freccia) sul lato destro. Verrà visualizzata la pagina Scheda dello Store predefinita.
  3. Vai alla sezione Google Play Games su PC e carica l'immagine in Immagine in primo piano per l'acquisto in-app di Google Play Games su PC (Windows).
  4. Fai clic su Salva.

Inviare le modifiche per la revisione

  1. In Play Console, nel menu a sinistra, seleziona Panoramica della pubblicazione.
  2. Nella sezione Modifiche non ancora inviate per la revisione, fai clic su Invia modifiche per la revisione.

Una volta che il team di revisione avrà approvato le modifiche, il tuo gioco sarà rilevabile su Google Play.