Services de jeux Play pour C++

Suite à l'arrêt de l'API Google Sign-In, nous allons supprimer le SDK v1 pour les jeux en 2026. Après février 2025, vous ne pourrez plus publier de titres qui viennent d'être intégrés au SDK v1 de Jeux sur Google Play. Nous vous recommandons d'utiliser plutôt le SDK v2 de Jeux.
Bien que les titres existants avec les intégrations de jeux v1 précédentes continuent de fonctionner pendant quelques années, nous vous encourageons à migrer vers la v2 à partir de juin 2025.
Ce guide explique comment utiliser la version 1 du SDK des services de jeux Play. Le SDK C++ pour les services de jeux Play v2 n'est pas encore disponible.

Le SDK C++ des services de jeux Google Play fournit une API C++ à utiliser avec les services de jeux Google Play. Il est destiné aux développeurs qui disposent déjà d'une implémentation C++ de leur jeu.

Actuellement, le SDK implémente les services suivants :

  • Autorisation
  • Exploits
  • Classements
  • Événements
  • Jeux enregistrés
  • Nearby Connections (Android uniquement)
  • Statistiques des joueurs

Concepts

De manière générale, vous utilisez le SDK en procédant comme suit :

  1. Configurez une plate-forme pour Android.
  2. Utilisez un GameServices::Builder pour configurer et construire un objet GameServices. L'objet GameServices tente automatiquement de se connecter et renvoie le résultat via un rappel OnAuthActionFinished(). Notez le résultat renvoyé par le rappel. Si la tentative de connexion automatique a échoué, vous pouvez afficher un bouton permettant aux utilisateurs de se connecter.
  3. Après avoir reçu le résultat OnAuthActionFinished(), vous pouvez utiliser l'objet GameServices et ses gestionnaires enfants pour effectuer des appels aux services de jeux Play, y compris :

    • Se connecter (après l'échec de l'autorisation) : StartAuthorizationUI()
    • Débloquer des succès : Achievements().Unlock()
    • Afficher les succès à l'aide de l'UI intégrée : Achievements().ShowAllUI()
    • Envoyer un score élevé : Leaderboards().SubmitScore()
    • Se déconnecter : SignOut()
  4. Lorsque vous avez terminé d'utiliser l'objet GameServices, réinitialisez-le ou détruisez-le.

Plus précisément :

  1. Initialisez une configuration de plate-forme : il s'agit d'un objet contenant des informations d'initialisation spécifiques à la plate-forme. Sur Android, la configuration de la plate-forme contient la VM Java et un pointeur vers le Activity actuel :

    // In android_main(), create a platform configuration
    // and bind the object activity.
    // Alternately, attach the activity in JNI_Onload().
    gpg::AndroidPlatformConfiguration platform_configuration;
    platform_configuration.SetActivity(state->activity->clazz);
    
  2. Construisez un objet GameServices : cet objet est le principal point d'entrée pour la fonctionnalité des services de jeux Google Play. Les instances GameServices sont créées avec GameServices::Builder.

    Dans la plupart des implémentations, un objet GameServices donné persistera tant que votre environnement C le fera. Vous n'avez pas besoin de le réinitialiser lorsque votre Activity Android est mis en pause et reprend.

    // Creates a GameServices object that has lambda callbacks.
    game_services_ = gpg::GameServices::Builder()
            .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
            .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
                is_auth_in_progress_ = true;
                started_callback(op);
            })
            .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                         gpg::AuthStatus status) {
                LOGI("Sign in finished with a result of %d", status);
                is_auth_in_progress_ = false;
                finished_callback(op, status);
            })
            .Create(pc);
    
  3. Utilisez les classes Manager pour gérer votre objet GameServices. Les gestionnaires sont accessibles à partir d'une instance GameServices et regroupent les fonctionnalités associées. Par exemple, les gestionnaires de succès et de classements. Ils ne contiennent pas d'état visible par l'utilisateur. Les gestionnaires sont renvoyés par référence, et l'instance GameServices qui les contient contrôle leur cycle de vie. Votre client ne doit jamais conserver de référence à un compte administrateur. Au lieu de cela, votre client doit conserver l'instance GameServices.

    Les gestionnaires renvoient des données via des objets de type valeur immuable. Ces valeurs reflètent une vue cohérente des données sous-jacentes au moment où la requête a été effectuée.

    // Submit a high score
    game_services_->Leaderboards().SubmitScore(leaderboard_id, score);
    
    // Show the default Achievements UI
    game_services_->Achievements().ShowAllUI();
    
  4. Lorsque vous avez terminé d'utiliser l'objet GameServices, nettoyez-le en appelant reset() sur le unique_ptr qui le possède, ou en laissant le unique_ptr le détruire automatiquement lorsqu'il sort de la portée.

Modèle de threading

Sauf indication contraire, toutes les méthodes GameServices et Manager disposent d'implémentations asynchrones et thread-safe. Elles peuvent être appelées sur n'importe quel thread sans verrouillage externe et s'exécutent dans un ordre cohérent avec leur ordre d'invocation.

Les méthodes d'accesseur (celles qui lisent l'état) se déclinent en deux variantes principales. Le premier type de méthode (avec des noms tels que FetchProperty()) fournit ses résultats de manière asynchrone à un rappel fourni. Le second (avec des noms tels que FetchPropertyBlocking()) renvoie ses résultats de manière synchrone au thread appelant.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Tous les rappels utilisateur sont appelés sur un thread de rappel dédié. Ce thread est potentiellement distinct de tout concept de plate-forme de "thread principal" ou de "thread d'UI". Vous devez également essayer de vous assurer que les rappels utilisateur s'exécutent rapidement. Un thread de rappel bloqué peut entraîner des problèmes visibles par l'utilisateur (par exemple, un délai dans l'exécution d'une demande de déconnexion).

Informations spécifiques à la plate-forme

Pour commencer à utiliser le SDK Play Jeux C++ sur Android, consultez le guide de démarrage rapide.

Complément d'informations

Pour en savoir plus, veillez à lire la documentation de la classe fournie dans le SDK C++ des services de jeux Google Play et consultez les exemples qui montrent comment utiliser le SDK.

Si votre jeu utilise un serveur backend, consultez Activer l'accès côté serveur aux services de jeux Google Play.