Premiers pas avec le plug-in Google Play Jeux pour Unity

Cet article explique comment configurer votre projet Unity afin d'utiliser le plug-in Google Play Jeux pour Unity. Nous verrons entre autres comment configurer le projet, choisir une plate-forme de réseau social et permettre au joueur de se connecter.

Avant de commencer

Installation du plug-in

  1. Obtenez le plug-in à l'aide de l'une des options suivantes :

    • Clonez le Dépôt GitHub dans votre système de fichiers.

    • Téléchargez le Dépôt GitHub en tant que fichier ZIP, puis décompressez le fichier.

  2. Recherchez le fichier unitypackage dans le répertoire current-build. Ce fichier est le plug-in. Il devrait ressembler à ceci :

      current-build/GooglePlayGamesPluginForUnity-X.YY.ZZ.unitypackage
    
  3. Ouvrez votre projet de jeu dans Unity.

  4. Importez le fichier unitypackage dans les éléments de votre projet en cliquant sur l'élément de menu Assets > Import Package > Custom Package (Assets > Importer le package > Package personnalisé).

  5. Assurez-vous que votre plate-forme de compilation est définie sur Android.

    1. Dans le menu principal, cliquez sur File > Build Settings (Fichier > Paramètres de compilation).

    2. Sélectionnez Android, puis cliquez sur Switch Platform (Changer de plate-forme).

    3. Vous devriez voir un nouvel élément de menu sous Window > Google Play Games (Fenêtre > Google Play Jeux). Si ce n'est pas le cas, actualisez les éléments en cliquant sur Assets > Refresh (Assets > Actualiser), puis réessayez de définir la plate-forme de compilation.

Obtenir des ressources Android depuis la Play Console

Chaque réussite, classement et événement que vous créez dans la Play Console inclut une ressource Android que vous utilisez lorsque vous configurez votre projet Unity.

  1. Ressources Android pour votre jeu

    1. Dans la Play Console, ouvrez le projet des services de jeux Play pour votre jeu.

    2. Cliquez sur l'onglet Achievements (Succès), puis sur Get resources (Obtenir des ressources).

    3. Dans la fenêtre Export resources (Exporter les ressources), cliquez sur l'onglet Android.

    4. Sélectionnez et copiez le contenu XML.

Configurer votre projet Unity

  1. Ajoutez les ressources Android à votre projet Unity.

    1. Dans Unity, cliquez sur ** Window > Google Play Games > Setup (Fenêtre > Google Play Jeux > Configuration). > Configuration Android **.

    2. Effectuez les tâches suivantes dans les fenêtres de configuration :

    3. Répertoire pour l'enregistrement des constantes : le dossier du fichier des constantes.

    4. Nom de la classe des constantes : nom de la classe C# à créer, espace de noms compris.

    5. Définition des ressources : collez ici les données relatives aux ressources Android issues de la Play Console.

    6. Web client ID (Identifiant du client Web) : identifiant client de l'application Web associée. Cela n'est nécessaire que si vous disposez d'un backend Web pour votre jeu et que vous avez besoin d'un code d'authentification de serveur pour échanger un jeton d'accès par le serveur backend ou si vous avez besoin d'un jeton d'identification pour que le joueur puisse effectuer des appels d'API hors du jeu.

    7. Cliquez sur Configurer. Votre jeu est ainsi configuré avec l'identifiant client et génère une classe C# contenant des constantes pour chacune de vos ressources Android.

Configuration d'Android

Configurez le chemin d'installation de votre SDK Android dans Unity. Pour ce faire, accéder au menu des préférences, dans la section Outils externes.

Pour configurer votre jeu Unity afin de l'exécuter avec Google Play Jeux sur Android, commencez par ouvrir Android SDK Manager et vérifiez que vous avez téléchargé les packages suivants. Selon que vous utilisez le SDK Manager d'Android Studio ou celui du SDK autonome, le nom des composants peut être différent. – Services Google Play – Bibliothèque Android Support – Dépôt Maven local pour les bibliothèques Support (ou "Android Support") – Dépôt Google – Android 6.0 (API 23) (ceci n'a aucune incidence sur la version minimale du SDK).

Configurez ensuite le nom du package de votre jeu. Pour ce faire, cliquez sur File > Build Settings (Fichier > Paramètres de compilation), sélectionnez la plate-forme Android, puis cliquez sur Player Settings (Paramètres du joueur) pour afficher la fenêtre des paramètres du joueur Unity. Dans cette fenêtre, recherchez le paramètre Bundle Identifier (Identifiant de bundle) sous Other Settings (Autres paramètres). Saisissez-y le nom du package (par exemple, com.exemple.mon.super.jeu).

Pour vous connecter aux services de jeux Play, vous devez signer votre fichier APK et vous assurer de le faire avec le bon certificat, c'est-à-dire celui correspondant au certificat d'empreinte digitale SHA1 saisie dans la Play Console lors de la configuration.

Ensuite, cliquez sur l'élément de menu Window > Google Play Games|Setup > Android setup (Fenêtre > Google Play Jeux > Configuration – Configuration Android). L'écran de configuration d'Android s'affiche.

Saisissez le nom de la classe Constants. Il s'agit du nom de la classe complète qui sera actualisée (ou créée) et qui contient les identifiants des ressources du jeu. Le format du nom est <namespace>.<classname>. Exemple : AwesomeGame.GPGSIds

Collez les données de définition des ressources. Il s'agit des données XML de la Google Play Console. Elles contiennent les identifiants des ressources et l'identifiant d'application pour Android.

Pour accéder à ces données dans la Google Play Console, cliquez sur "Get resources" (Obtenir des ressources) sur l'une des pages de ressources (par exemple, les succès ou les classements), puis sur "Android".

Après avoir collé les données dans la zone de texte, cliquez sur le bouton Configurer.

Remarque : Si vous utilisez une application Web ou un serveur backend avec votre jeu, vous pouvez associer l'application Web au jeu pour activer le jeton d'identification et/ou l'adresse e-mail du joueur. Pour ce faire, associez une application Web au jeu dans la Google Play Console, puis saisissez l'identifiant client de l'application Web dans la boîte de dialogue de configuration.

Instructions supplémentaires pour créer des applications pour Android sous Windows

Si vous utilisez Windows, vous devez vous assurer qu'Unity peut accéder à votre installation du SDK Java. Voici comment procéder :

  1. Définissez la variable d'environnement JAVA_HOME pour le chemin d'installation de votre SDK Java (par exemple, C:\Program Files\Java\jdk1.7.0_45).
  2. Ajoutez le dossier bin du SDK Java à votre variable d'environnement PATH (par exemple, C:\Program Files\Java\jdk1.7.0_45\bin).
  3. Redémarrez.

Pour modifier des variables d'environnement : Sous Windows 2000/XP/Vista/7, effectuez un clic droit sur Poste de travail, puis Propriétés, puis accédez à Propriétés système avancées (ou Propriétés système puis cliquez sur Paramètres systèmes avancés), puis cliquez sur Variables d'environnement. Sous Windows 8, appuyez sur Windows + W, puis recherchez Variables d'environnement. Pour en savoir plus, consultez la documentation de votre version de Windows.

Exécuter le projet

Si vous travaillez avec l'exemple Smoketest, vous devriez pouvoir créer et exécuter le projet à ce stade. La tentative de connexion automatique s'affichera au démarrage de Smoketest.

Pour compiler et exécuter sur Android, cliquez sur File > Build Settings (Fichier > Paramètres de compilation), sélectionnez la plate-forme Android, puis Switch to Platform (Passer à cette plate-forme), puis Build and Run (Compiler et exécuter).

Choisir une plate-forme de réseau social

Le plug-in Google Play Jeux met en œuvre l'interface de réseau social d'Unity pour sa compatibilité avec les jeux qui utilisent déjà cette interface lors de l'intégration à d'autres plates-formes. Cependant, certaines fonctionnalités propres à Play Jeux sont proposées en tant qu'extensions de l'interface de réseau social standard fournie par Unity.

Les appels d'API standards sont accessibles via l'objet Social.Active, qui fait référence à une interface ISocialPlatform. Vous pouvez accéder aux extensions Google Play Jeux non standards en castant l'objet Social.Active dans la classe PlayGamesPlatform, où des méthodes supplémentaires sont disponibles.

Utiliser le plug-in sans remplacer la plate-forme de réseau social par défaut

Lorsque vous appelez PlayGamesPlatform.Activate, Google Play Jeux devient votre implémentation de plate-forme de réseau social par défaut. Cela signifie que les appels statiques vers les méthodes dans Social et Social.Active seront effectués par le plug-in Google Play Jeux. C'est le comportement souhaité pour la plupart des jeux utilisant ce plug-in.

Toutefois, si, pour une raison quelconque, vous souhaitez que l'implémentation par défaut reste accessible (par exemple, pour envoyer des réussites et des classements à une autre plate-forme de réseau social), vous pouvez utiliser le plug-in Google Play Jeux sans remplacer l'option par défaut. Voici comment procéder :

  1. N'appelez pas PlayGamesPlatform.Activate.
  2. Si Xyz est le nom d'une méthode que vous souhaitez appeler sur la classe Social, n'appelez pas Social.Xyz. Appelez plutôt PlayGamesPlatform.Instance.Xyz.
  3. N'utilisez pas Social.Active lorsque vous interagissez avec Google Play Jeux. Utilisez plutôt PlayGamesPlatform.Instance.

Ainsi, vous pouvez même envoyer des scores et des réussites simultanément à au moins deux plates-formes de réseaux sociaux :

    // Submit achievement to original default social platform
    Social.ReportProgress("MyAchievementIdHere", 100.0f, callback);

    // Submit achievement to Google Play
    PlayGamesPlatform.Instance.ReportProgress("MyGooglePlayAchievementIdHere", 100.0f, callback);

Valider le service de connexion

À l'ouverture de votre jeu, une connexion aux services de jeux Play est automatiquement effectuée à l'aide du service de connexion. Si la connexion aboutit, votre jeu affiche une invite de connexion et peut utiliser le plug-in Google Play Jeux pour Unity.

Si un utilisateur n'a jamais utilisé Google Play Jeux sur son appareil, il est automatiquement redirigé vers un écran de configuration unique pour créer un compte Play Jeux.

Dans la méthode Start de votre script, écoutez le résultat de la tentative de connexion automatique, récupérez l'état d'authentification et désactivez les fonctionnalités des services de jeux Play si l'utilisateur n'est pas connecté.

    using GooglePlayGames;

    public void Start() {
      PlayGamesPlatform.Instance.Authenticate(ProcessAuthentication);
    }

    internal void ProcessAuthentication(SignInStatus status) {
      if (status == SignInStatus.Success) {
        // Continue with Play Games Services
      } else {
        // Disable your integration with Play Games Services or show a login button
        // to ask users to sign-in. Clicking it should call
        // PlayGamesPlatform.Instance.ManuallyAuthenticate(ProcessAuthentication).
      }
    }
}

Le code de résultat est une énumération que vous pouvez utiliser pour identifier la raison d'un échec de connexion.

Si vous préférez utiliser la plate-forme de réseaux sociaux Unity, vous pouvez également utiliser le code suivant :

  using GooglePlayGames;

  public void Start() {
    PlayGamesPlatform.Activate();
    Social.localUser.Authenticate(ProcessAuthentication);
  }

Vous ne pouvez pas effectuer d'appels à l'API Google Play Jeux tant qu'Authenticate n'a pas renvoyé une valeur de retour. Par conséquent, nous vous recommandons d'afficher un écran d'attente jusqu'à ce que le rappel soit appelé. De la sorte, les utilisateurs ne pourront pas commencer à jouer tant que le processus d'authentification ne sera pas terminé.

Récupérer les codes d'authentification du serveur

Pour accéder aux API Google sur un serveur Web backend pour le compte du joueur actuel, vous devez obtenir un code d'authentification auprès de l'application cliente et le transmettre à l'application de votre serveur Web. Ce code peut ensuite être échangé contre un jeton d'accès permettant d'appeler les différentes API. Pour en savoir plus sur ce workflow, consultez Google Sign-In pour les sites Web.

Voici comment procéder pour obtenir le code d'accès côté serveur :

  1. Configurez l'identifiant client Web de l'application Web associée à votre jeu dans la Play Console.

  2. Appelez PlayGamesPlatform.Instance.RequestServerSideAccess une fois le joueur authentifié pour obtenir le code d'accès côté serveur.

  3. Transmettez ce code à votre application de serveur.

  PlayGamesPlatform.Instance.RequestServerSideAccess(
    /* forceRefreshToken= */ false,
    code -> {
      // send code to server
    });

Effectuer la configuration et ajouter des fonctionnalités