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

Esempio di contenuti 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, l'eseguibile del gioco 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 per la 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 dell'utente ed è consigliabile verificare che l'inizializzazione sia andata a buon fine prima di eseguire il rendering della finestra del gioco. In questo modo si offre la migliore esperienza utente, perché gli errori vengono rilevati e risolti il prima possibile e si evita che la finestra del gioco venga visualizzata brevemente nei casi in cui il processo del 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 il callback di continuazione deve essere completato 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#), chiudi il processo del gioco il prima possibile. Il runtime dell'SDK tenterà di aiutare l'utente senza che il gioco debba eseguire ulteriori azioni. Ad esempio, se l'utente non possiede una licenza valida per il gioco, Google Play Games gli chiederà di acquistare una copia. In caso di altri errori, devi chiudere anche il processo del gioco perché non potrai utilizzare l'SDK per eseguire operazioni critiche, ad esempio verificare che l'utente possieda una licenza valida per il 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.

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

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

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

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

Completa questi passaggi di integrazione aggiuntivi se il gioco utilizza più processi e l'SDK Play Games 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 gioco e poi il launcher avvia il processo del gioco che interagirà con l'SDK.

1. Il processo avviato direttamente da Google Play Games su PC deve verificare che l'inizializzazione dell'SDK Play Games PC sia andata a buon fine.

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

2. Per utilizzare l'SDK Play Games PC in un processo figlio, inoltra i parametri della riga di comando al processo figlio 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 Games 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 figlio (YourGame.exe) che utilizza l'SDK Play Games per PC. Per consentire questa operazione, il processo del gioco avviato da Google Play Games su PC inoltra i parametri della riga di comando che gli sono stati forniti al processo figlio.

3. Chiudi tutti i processi quando il gioco smette di essere eseguito.

   Quando un utente chiude il gioco o il gioco viene chiuso 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 verrà avviato dal client di Google Play Games su PC, le nuove modifiche, ad esempio il passaggio a un account attivo diverso, avranno effetto.

Passaggi successivi

Utilizza l'SDK durante lo sviluppo nell'IDE:

• Attiva modalità sviluppatore

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

• Vendi beni digitali con Fatturazione Play
• Misura il tuo marketing con Play Install Referrer
• Proteggi il tuo gioco con Play Integrity per PC