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 di installazione da parte 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 WAB (Windows App Bundle). Per creare un file WAB, ​segui questi passaggi:

  1. Scarica lo strumento di pubblicazione di Google Play. Puoi eseguire questo strumento sulla riga di comando di Windows o su PowerShell.

  2. Crea il file di configurazione di pubblicazione di 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. 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 in 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 l'eseguibile come amministratore.
        • "false": esegui l'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 di installazione all'interno del WAB. Questo percorso può essere assoluto o relativo alla directory principale della configurazione di pubblicazione su 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 tuo gioco.

      • UNIQUE_REGISTRY_PATH: il percorso della chiave del Registro di Windows. Questo percorso deve essere fornito in relazione a un hive del registro, 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 a 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.

        L'eseguibile specificato in INSTALLER_PATH deve creare queste chiavi del Registro di sistema. Prima del completamento dell'installazione, devono essere create le coppie di chiavi del Registro di sistema e nomi dei valori 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 voci di registro corrispondenti per tutti e tre. Google Play Games su PC utilizza questi valori per avviare e disinstallare il gioco. Se il tuo gioco utilizza un launcher, questo percorso deve puntare alla chiave di registro contenente le informazioni di installazione del launcher e il valore nella voce di registro specificata da launch-path-registry-location deve puntare 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 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 l'eseguibile come amministratore.
        • "false": esegui l'eseguibile come utente corrente.

      • RELATIVE_PATH_TO_LAUNCHER_EXE: il percorso dell'eseguibile del launcher o 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 di 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.

        • In caso di più argomenti associati a un eseguibile, questi devono essere separati da uno spazio.
        • Se richiesto dall'eseguibile, gli argomenti devono essere preceduti da "--" o "-".

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

        • "true": esegui l'eseguibile come amministratore.
        • "false": esegui l'eseguibile come utente corrente.

    Esempio di file di configurazione della pubblicazione su Google Play

    Prendi in considerazione 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 Play sulla riga di comando di Windows o su 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

    Considera che nella directory di lavoro corrente sono presenti il file binario dello strumento di pubblicazione Play playpublishingtool.exe, la configurazione di pubblicazione 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 WAB con il nome, ad esempio, installer_bundle.wab nella stessa directory, il comando sarebbe simile a questo:

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

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

    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) Attivare la riproduzione automatica all'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 subito dopo il completamento della procedura di installazione. Questa funzionalità offre un'esperienza utente fluida, in quanto consente di passare direttamente al giocatore nel gioco, con autenticazione completa all'interno dell'ecosistema Google Play Giochi su PC.

    Come funziona

    Quando attivi la funzionalità, Google Play Games su PC trasmette un token di sessione al processo di installazione di terze parti utilizzando gli argomenti della riga di comando. L'installer è quindi responsabile dell'estrazione di questo token e del suo utilizzo per avviare l'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 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 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 sessione nel programma di installazione

      Quando il programma di installazione viene avviato dal client GPG, riceve 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.
      • Avvia: 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 la partita.

    3. Gestione degli errori e fallback

      • Recupero del token: se, per qualsiasi motivo, GPG non riesce a generare o trasmettere 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 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: sei responsabile 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 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 è obbligatorio solo la prima volta che pubblichi un gioco.

  1. In Play Console, nel menu a sinistra, seleziona Test e rilascio > 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, quindi 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:

  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 Giochi su PC da aggiungere.
  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 Test e release > 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 Pacchetto app Windows, fai clic su Modifica e carica il file WAB.

Configurare i requisiti del PC Windows

Per configurare i requisiti del PC Windows:

  1. In Play Console, nel menu a sinistra, seleziona Aumenta il numero di 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 gli 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 modifiche per la revisione.

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