面向 C 和 C++ 的 Play 游戏服务使用入门

本指南介绍了如何设置原生 C 或 C++ 游戏项目，以使用 Play 游戏服务 v2 原生 SDK 并集成登录服务。需要集成登录服务才能将其他 Play 游戏服务功能集成到您的游戏中以及将 Play 游戏服务集成到您的后端游戏服务器中。

支持的功能

Play 游戏服务 v2 原生 SDK 目前处于 Beta 版阶段，仅支持登录服务。尚不支持其他 Play 游戏服务功能。

API 参考文档

SDK 的头文件包含 API 的参考文档。头文件位于 SDK 文件的 include 文件夹中，在将项目与 SDK 代码库同步后，您可以找到该文件夹。

要求

使用原生 C 或 C++ 作为主要编程语言的游戏项目。
您的游戏项目和开发环境必须设置 Gradle 构建系统。

前期准备

您必须在 Google Play 管理中心内设置 Play 游戏服务。

设置游戏项目

完成以下步骤以设置您的游戏项目。

更新 CMakeLists.txt

在您的 CMakeLists.txt 文件中，添加如下代码：

  find_package(com.google.android.gms.games.v2.c REQUIRED CONFIG)

  // link games_static for -DANDROID_STL=c++_static or default
  // link games_shared for -DANDROID_STL=c++_shared
  target_link_libraries(
    app PUBLIC com.google.android.gms.games.v2.c::games_static)

更新 build.gradle

在应用级 build.gradle 文件中，执行以下操作：

确保已启用 prefab 构建功能。
添加 Play 游戏服务 v2 原生 SDK 的依赖项：
- com.google.android.gms:play-services-games-v2-native-c:17.0.0-beta1

示例如下：

  android {
    ...
    buildFeatures {
      prefab true
    }
    ...
  }
  dependencies {
    ...
    implementation "com.google.android.gms:play-services-games-v2-native-c:17.0.0-beta1"
  }

更新 AndroidManifest.xml

在 AndroidManifest.xml 文件中，定义您的 Play 游戏服务项目 ID。为此，请将以下几行代码添加到该文件中：

<manifest>
  <application>
    <meta-data android:name="com.google.android.gms.games.APP_ID"
               android:value="@string/game_services_project_id"/>
  </application>
</manifest>

为项目 ID 创建字符串资源。这样一来，您的游戏便可以在构建时访问该项目 ID。如需创建资源，请创建文件 project_root/app/src/main/res/values/games-ids.xml，并添加以下内容：
```
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="game_services_project_id"
            translatable="false">add your Project ID here</string>
</resources>
```
构建和测试游戏。如果成功，当您启动游戏时，它会显示登录提示或成功的登录横幅。

获取玩家 ID

您的游戏可以通过检索已登录玩家的玩家 ID 来访问该玩家的信息。您可以通过调用 GetPlayerID 函数来检索玩家 ID，如以下示例所示。

#include <assert.h>
#include "gni/gni.h"
#include "gni/gni_task.h"
#include "pgs/pgs_play_games.h"
#include "pgs/pgs_players_client.h"

// A callback for a GniTask returned from PgsPlayersClient_getCurrentPlayerId.
void OnGetCurrentPlayerIdCompleteCallback(GniTask *task, void *user_data) {

   if (!GniTask_isSuccessful(task)) {
      const char *error_message = nullptr;
      GniTask_getErrorMessage(task, &error_message);

      // Log error message here.

      GniString_destroy(error_message);
      GniTask_destroy(task);
      return;
   }

   const char *result = nullptr;
   PgsPlayersClient_getCurrentPlayerId_getResult(task, &result);

   // Log player id here.

   GniString_destroy(result);
   GniTask_destroy(task);
}

// Gets the player ID.
void GetPlayerId(jobject main_activity) {
   static const PgsPlayersClient *players_client =
           PgsPlayGames_getPlayersClient(main_activity);

   GniTask *get_current_player_id_task =
           PgsPlayersClient_getCurrentPlayerId(players_client);
   assert(get_current_player_id_task != nullptr);
   GniTask_addOnCompleteCallback(get_current_player_id_task,
                                 OnGetCurrentPlayerIdCompleteCallback,
                                 nullptr);
}

// Entry point for our test app
void TestPGSNative(JNIEnv *env, jobject main_activity) {
   JavaVM *java_vm;
   env->GetJavaVM(&java_vm);

   GniCore_init(java_vm, main_activity);

   GetPlayerId(main_activity);
}

如果玩家拒绝在游戏启动时自动显示初始 Play 游戏服务登录提示，他们可以在游戏会话期间改变主意。只要当前没有玩家登录，您就可以调用 PgsGamesSignInClient_signIn 来重新启动登录提示。

游戏服务器授权

玩家成功登录 Play 游戏服务后，您的游戏客户端可以请求服务器授权代码，您的后端游戏服务器可以使用该代码来与 Play 游戏服务进行安全通信。这样一来，您的游戏服务器就可以检索、更新和存储已登录玩家的数据。您可以通过调用 PgsGamesSignInClient_requestServerSideAccess 函数来检索服务器授权代码。

如需了解详情，请参阅服务器访问指南。