Migliorare il tuo gioco utilizzando l'SDK Play Games per PC

Con l'SDK Play Giochi per PC puoi accedere ai servizi Google Play per creare e monetizzare il tuo gioco sui PC. Vendi contenuti digitali utilizzando Play Billing, accedi senza problemi utilizzando Play Giochi e verifica che i tuoi utenti abbiano un diritto valido per la tua applicazione con Play Integrity.

Iniziamo?

Prerequisiti

• Crea una voce per l'app in Play Console e rivendica un nome del pacchetto Play.

• Scarica e installa Google Play Giochi per PC e accedi con il tuo Account Google.

Passaggio 1: aggiungi l'SDK al tuo progetto

Passaggio 2: aggiungi un file manifest

Prima di poter utilizzare l'SDK all'interno del gioco, devi associare l'eseguibile del gioco al nome del pacchetto Play che hai rivendicato in Play Console. A questo scopo, aggiungi un file manifest.xml nella stessa directory dell'eseguibile del gioco.

Contenuti di esempio di manifest.xml:

<?xml version="1.0" encoding="utf-8"?>
<Manifest version="1">
    <Application>
        <PackageName>com.example.package</PackageName>
    </Application>
</Manifest>

Esempio di posizionamento di manifest.xml:

C:\Program Files
└───Example Game
    ├───Game.exe
    └───manifest.xml

Passaggio 3: firma digitalmente il gioco

Prima che il gioco possa utilizzare l'SDK, il relativo eseguibile deve essere firmato digitalmente utilizzando una firma digitale Authenticode. Per istruzioni su come firmare un eseguibile, consulta la documentazione su SignTool .

Una volta completata la procedura di firma digitale del gioco, invia le informazioni sul certificato al tuo rappresentante Google per la configurazione.

Passaggio 4: inizializza l'SDK

Inizializza l'SDK durante la sequenza di avvio del gioco. Questa operazione deve essere eseguita automaticamente senza richiedere alcuna interazione utente ed è consigliabile verificare l'inizializzazione prima di visualizzare la finestra di gioco. In questo modo si offre la migliore esperienza utente, rilevando e risolvendo gli errori il prima possibile ed evitando che la finestra di gioco venga visualizzata brevemente nei casi in cui il processo di gioco deve essere chiuso.

Inizia a utilizzare l'SDK chiamando GooglePlayInitialize (C++) / GooglePlayInitialization.InitializeAsync (C#) per inizializzare l'API. In questo modo verrà configurato lo stato globale, verrà stabilita la connessione con il runtime dell'SDK e verrà verificato che l'applicazione sia stata avviata correttamente. Questa operazione DEVE essere chiamata e la callback di continuazione deve essere completata con InitializeResult::ok() (C++) / Result.IsOk (C#) uguale a true prima che possa essere utilizzata qualsiasi altra API.

  // Initialize the SDK as part of the startup sequence of your application.
  auto promise = std::make_shared<std::promise<InitializeResult>>();
  GooglePlayInitialize(
    [promise](InitializeResult result) {
      promise->set_value(std::move(result));
    });

  auto initialize_result = promise->get_future().get();
  if (initialize_result.ok()) {
    // The SDK succeeded with initialization. Continue with the startup sequence
    // of the game.
    // ...
  } else if (initialize_result.code() == InitializationError::kActionRequiredShutdownClientProcess) {
    // The SDK failed to initialize and has requested that your game process exit
    // as soon as possible.
    exit(1);
  } else {
    // The SDK failed to initialize for an alternative reason. It is still
    // generally recommended that you exit the game process as soon as possible,
    // because it won't be possible to access any APIs in the SDK. Critical
    // operations such as verifying the user owns a valid license to your game
    // won't be possible.
    // ...
  }

  // SDK Clients
  private BillingClient _billingClient;
  private IntegrityClient _integrityClient;

  // Stored product information
  private string _offerToken;

  private async void InitializeSDK()
  {
      // The factory provides the necessary handler for initialization.
      var initializationHandler = PlayPcSdkFactory.InitializationHandler;
      var result = await GooglePlayInitialization.InitializeAsync(initializationHandler);

      if (result.IsOk)
      {
          // Use the factory to get Unity-compatible instances of the clients
          _billingClient = PlayPcSdkFactory.CreateBillingClient();
          _integrityClient = PlayPcSdkFactory.CreateIntegrityClient();

          // SDK is ready for use
      }
      else
      {
          // Handle specific, actionable errors
          if (result.Code == InitializationError.ActionRequiredShutdownClientProcess)
          {
              Log("This game must be launched through the Google Play Games client. Please exit all game processes immediately, GPG will relaunch the game safely.");
              Application.Quit();
          }
      }
  }

Se l'inizializzazione non va a buon fine con il codice kActionRequiredShutdownClientProcess (C++) / InitializationError.ActionRequiredShutdownClientProcess (C#), esci dal processo di gioco il prima possibile. Il runtime dell'SDK tenterà di assistere l'utente senza che il gioco richieda ulteriori azioni. Ad esempio, se l'utente non dispone di una licenza valida per il gioco, Google Play Giochi gli chiederà di acquistare una copia. Per altri errori, devi anche uscire dal processo di gioco perché non potrai utilizzare l'SDK per eseguire operazioni critiche, come verificare che l'utente possieda una licenza valida per il tuo gioco.

Una risposta non riuscita può indicare una delle seguenti condizioni:

• Il runtime dell'SDK non è installato, non è in esecuzione sul dispositivo o è una versione precedente non compatibile con l'SDK integrato nel gioco.

• L'ambiente di runtime dell'SDK non è riuscito a verificare l'identità dell'applicazione del gioco. Ciò potrebbe essere dovuto a un manifest.xml non valido o all'utilizzo dell'SDK senza attivare la modalità sviluppatore durante lo sviluppo. Senza questo, l'eseguibile del gioco deve essere firmato digitalmente con il certificato digitale registrato con il nome di pacchetto Play.

• L'eseguibile del gioco non è stato avviato tramite il client Google Play Giochi.

• L'utente attivo in Google Play Giochi non dispone di una licenza per l'applicazione.

Passaggio 5: (facoltativo) supporto di più processi di gioco

Completa questi passaggi di integrazione aggiuntivi se il tuo gioco utilizza più processi e l'SDK Play Giochi per PC viene utilizzato da un processo diverso da quello avviato da Google Play Giochi su PC. Ad esempio, se Google Play Giochi su PC avvia il launcher del tuo gioco e poi il launcher avvia il processo del gioco che interagirà con l'SDK.

1. Il processo avviato direttamente da Google Play Giochi per PC deve verificare l'inizializzazione riuscita dell'SDK Play Games PC.

   In questo modo, si offre la migliore esperienza utente mostrando gli errori il prima possibile. Tieni presente che anche il processo secondario che utilizza l'SDK deve eseguire l'inizializzazione oltre al processo avviato direttamente.

2. Per utilizzare l'SDK per PC di Play Giochi in un processo secondario, inoltra i parametri della riga di comando al processo secondario generato.

   Esempio di inoltro dei parametri della riga di comando:

   Processes hierarchy tree:
   
   GooglePlayGames.exe
   └───YourGameLauncher.exe --gpg_args=abc --your_args=123
       └───YourGame.exe --gpg_args=abc --your_args=123
   

   In questo esempio vediamo una gerarchia di processi in cui Google Play Giochi per PC (GooglePlayGames.exe) avvia il gioco (YourGameLauncher.exe) con alcuni parametri di esempio (--gpg_args=abc --your_args=123). Il gioco genera quindi un processo secondario (YourGame.exe) che utilizza l'SDK Play Giochi per PC. Per consentire questa operazione, il processo di gioco avviato da Google Play Giochi per PC inoltra i parametri della riga di comando che gli sono stati forniti al processo secondario.

3. Esci da tutti i processi quando il gioco smette di funzionare.

   Quando un utente chiude il gioco o il gioco esce a causa di un errore di inizializzazione dell'SDK, ad esempio kActionRequiredShutdownClientProcess, chiudi tutti i processi generati dal gioco. In questo modo, la prossima volta che il gioco viene avviato dal client Google Play Giochi per PC, le nuove modifiche, come il passaggio a un altro account attivo, avranno effetto.

Passaggi successivi

Utilizza l'SDK durante lo sviluppo nel tuo IDE:

• Attivare la modalità sviluppatore

Aggiungi le funzionalità di Google Play PC alla tua app:

• Vendere beni digitali con la fatturazione Google Play
• Misurare il marketing con Play Install Referrer
• Proteggi il tuo gioco con Play Integrity per PC