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 assicurati che i tuoi utenti dispongano di un diritto valido per la tua applicazione con Play Integrity.

Iniziamo?

Prerequisiti

  • Crea una voce dell'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

  • Scarica l'SDK Play Giochi PC C++.

  • Copia la cartella delle intestazioni API includes/ nel codebase dell'applicazione.

  • Copia i file ridistribuibili da imports/ nel progetto dell'applicazione.

    • Collega il tuo progetto a play_pc_sdk.lib per consentire l'accesso ai contenuti di play_pc_sdk.dll.

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. Per farlo, 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 .

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 riuscita 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 per inizializzare l'API. In questo modo verificherai lo stato globale, ti connetterai al runtime dell'SDK e verificherai che l'applicazione sia stata avviata correttamente. Questa DEVE essere chiamata e la callback di continuazione deve essere completata con InitializeResult::ok() 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.
  // ...
}

Se l'inizializzazione non va a buon fine con il codice kActionRequiredShutdownClientProcess, esci dal processo di gioco il prima possibile. Il runtime dell'SDK tenterà di aiutare 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, è comunque consigliabile uscire dal processo di gioco il prima possibile, in quanto non utilizzerà l'SDK per eseguire operazioni critiche come la verifica 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 del 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

Se il tuo gioco utilizza più processi e prevede di utilizzare l'SDK Play Games per PC da un processo non avviato direttamente da Google Play Giochi per PC, sono necessari ulteriori passaggi di integrazione:

  1. Il processo avviato direttamente da Google Play Giochi per PC deve verificare l'inizializzazione 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 Play Giochi per PC 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 --foo=abc --bar=123
    └───YourGame.exe --foo=abc --bar=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 (--foo=abc --bar=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:

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