Pubblicazione del programma di installazione

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

Con il flusso Installato dallo 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 Giochi nel tuo gioco.

Crea un pacchetto del 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 Windows App Bundle (WAB). Per creare un file WAB, ​segui questi passaggi:

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

  2. Crea il file di configurazione della pubblicazione su Google Play con un nome qualsiasi. 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 tuo gioco. Questo è l'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 contenere 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 WAB caricati per il tuo gioco. Ad esempio: 1.0, 1.0.1-beta, 2025.11.24, v1.rc1.

      • INSTALLER_REQUIRES_ELEVATION: indica se l'eseguibile del programma di installazione deve essere eseguito come amministratore per completare il processo 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 valore è facoltativo e il valore predefinito è false. Per saperne di più, consulta Attivazione della riproduzione automatica.

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

      • <installation-path-registry-location>: il percorso del registry utilizzato da Google Play Giochi per rilevare se il gioco è installato. Anche se il tuo gioco utilizza un programma di avvio personalizzato, questo percorso deve puntare alla chiave di registro univoca del gioco, non a quella del programma di avvio.

      • UNIQUE_REGISTRY_PATH: il percorso della chiave del registry di Windows. Questo percorso deve essere fornito in relazione a un hive del registry, 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 Giochi su PC cerca questo percorso prima in HKEY_LOCAL_MACHINE e poi in HKEY_CURRENT_USER, utilizzando il primo valore corrispondente che trova.

        L'eseguibile specificato in INSTALLER_PATH deve creare queste chiavi del Registro di sistema. Prima del completamento dell'installazione, è necessario creare queste coppie di chiavi del Registro di sistema e nomi di valori specificate in installation-path-registry-location, launch-path-registry-location e uninstall-path-registry-location. Anche se l'esempio utilizza InstallLocation e UninstallString, puoi specificare qualsiasi nome in questi tag <value-name>, purché il programma di installazione crei voci del registry corrispondenti per tutti e tre. Google Play Games su PC utilizza questi valori per avviare e disinstallare il gioco. Se il gioco utilizza un programma di avvio, il valore della voce del registry specificata da launch-path-registry-location deve puntare alla directory del programma di avvio (mentre installation-path-registry-location deve puntare alla chiave di registry univoca del gioco, non a quella del programma di avvio).

        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 per scrivere le voci del registro in HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node. Ad esempio, una scrittura su 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 programma di avvio o l'eseguibile 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 launcher o del file eseguibile del gioco all'interno della directory di installazione. Deve includere il nome file eseguibile del launcher o del gioco. Ad esempio, se il file di avvio 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 che devono essere passati al launcher o al gioco. Questa voce è facoltativa.

        • Se sono presenti più argomenti associati a un eseguibile, devono essere separati da uno spazio.
        • Gli argomenti devono essere preceduti da "--" o "-", se richiesto dall'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 Google Play

    Prendiamo in considerazione un gioco chiamato MyGame, con il programma di installazione del gioco game_installer.exe e l'Avvio app 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 di Play dalla riga di comando di Windows o da 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 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.

    Come utilizzare lo strumento di pubblicazione di Play

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

    La directory di lavoro corrente dovrebbe essere simile alla seguente:

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

    Per creare un 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
    

    In caso di esito positivo, 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) Attivazione della riproduzione automatica al momento dell'installazione dei giochi nativi per PC

    Google Play Games su PC ti consente di attivare una funzionalità di "avvio automatico", che avvia automaticamente il gioco subito dopo il completamento della procedura di installazione. Questa funzionalità offre un'esperienza utente fluida, in quanto consente al giocatore di accedere direttamente al gioco, con l'autenticazione completa nell'ecosistema di Google Play Giochi su PC.

    Come funziona

    Quando attivi la funzionalità, Google Play Giochi su PC trasmette un token di sessione al processo del programma 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 l'eseguibile del gioco in un contesto di autenticazione.

    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. Attiva la riproduzione automatica nella configurazione di pubblicazione di Play

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

      Esempio di estratto dei 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 impostato su true, GPG aggiungerà il token di sessione agli argomenti della riga di comando durante l'esecuzione del programma di installazione.
    2. Gestisci 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 programma di avvio 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 l'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 riesce a generare o passare un token di sessione (ad esempio, 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, poiché InitializeSDK non andrà comunque a buon fine.
      • Errori del programma di installazione: sei responsabile della solidità e della gestione degli errori del programma di installazione e della sequenza di lancio del gioco che avvia. GPG non ha il controllo sui processi che si verificano all'interno del programma di installazione dopo il lancio.

Pubblica il gioco utilizzando Play Console

Dopo aver creato il WAB per il tuo 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 Giochi su PC

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

  1. In Play Console, nel menu a sinistra, seleziona Testa e rilascia > 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.

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

Carica il file WAB

Per caricare il file WAB, segui questi passaggi:

  1. In Play Console, nel menu a sinistra, seleziona Testa e rilascia > 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 Giochi su PC per aggiungerlo.
  4. Nella sezione Google Play Giochi 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 Testa e rilascia > Produzione (link diretto).
  8. Nella pagina Produzione, seleziona Solo Google Play Giochi su PC (Windows) dal menu a discesa del fattore di forma.
  9. Nella scheda Windows App Bundle, fai clic su Modifica e carica il file WAB.

Configura i requisiti per PC Windows

Per configurare i requisiti del PC Windows:

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

Configura l'immagine per l'acquisto in-app

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

  1. In Play Console, nel menu a sinistra, seleziona Espandi 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) a destra. Verrà visualizzata la pagina Scheda dello Store predefinita.
  3. Vai alla sezione Google Play Giochi su PC e carica l'immagine in Immagine in primo piano per l'acquisto in-app di Google Play Giochi su PC (Windows).
  4. Fai clic su Salva.

Invia 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 le modifiche per la revisione.

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