Android

本文旨在介绍如何设置 Google 身份验证，让您的游戏可以使用 Player Network 登录鉴权服务通过 Google 渠道登录。

前提条件

1. 在 Google Play 管理中心设置您的游戏

note

对于 IEGG 项目，请联系 [miaruan (Ruan Mingjun)] 进行 Google 应用的注册和配置。

1. 创建 Google 应用

按照提示在 Google Play Console 上注册账号。

info

Google 收取25美元的服务费。请提前准备好信用卡。

进入 Google Play Console。
在 All apps 页面，点击 Create app，创建游戏应用。
输入应用信息。

2. 配置 Play 游戏服务

设置 Play 游戏服务，以管理游戏元数据并自动执行游戏制作和分发任务。

进入 Google Play Console。
在左侧导航栏中，选择 Grow users > Play Games Services > Setup and management > Configuration。
在 Which Play Games Services project do you want to use 下，选择对应的选项来创建 Play 游戏服务项目。
在 Properties 部分，点击 Edit Properties。
输入游戏基本信息，然后点击 Save changes。

3. 添加一个凭证，将 OAuth 2.0 客户端 ID 与游戏连接起来

进入 Google Cloud Platform。
在左侧导航栏中，点击 OAuth consent screen。
按照说明设置 OAuth consent screen。
在左侧导航栏上点击 Clients。
在 Clients 页面，选择 CREATE CLIENT > Create OAuth Client ID，创建 OAuth 客户端 ID。
在 Application type 列表中，点击 Android。
输入 Package Name 和 SHA-1 Certificate Fingerprint。
与开发团队确认 Package Name 和 SHA-1 Certificate Fingerprint。Android 的 OAuth 客户端要求用户在 KeyStore 中配置 SHA-1 证书指纹和软件包名称。请确保这两个值正确无误。否则，登录过程将出现异常。
点击 SAVE 完成配置。
进入 Android app 的详细信息页面，查看客户 ID 和客户密文。
点击 Audience > ADD USERS 添加登录测试用户。

4. 添加游戏测试人员

进入 Google Play Console。
在左侧导航栏中，选择 Grow users > Play Games Services > Setup and management > Testers。
在 Testers 选项卡中，点击 Add testers 为您的游戏添加测试人员。

note

在游戏应用发布之前，只有测试人员可以登录。请确保应用处于测试状态.

5. 配置成就和排行榜

在 Play 游戏服务 菜单下找到成就和 排行榜 功能，并根据需要进行配置。

图片：Google leaderboard

6. 获取 Google API ID

从 Google 云端平台面板访问信息中心。Google API ID 就是此页面上的 Project No.。

图片：Google ID

7. 获取 Client ID 和 Client secret

按照添加凭证以将 OAuth 2.0 客户端 ID 与游戏链接中的步骤获取应用信息。

图片：Google Web Client ID and Secret

步骤1：为 Google 登录配置 SDK

在 AndroidManifest 文件中，确保添加了所需权限。Google 需要访问网络。

<uses-permission android:name="android.permission.INTERNET"/>

打开项目的 INTLConfig.ini 文件：

INTLConfig.ini
[INTL environment]
# WARNING: You should change this URL to the production environment when you release your game.
INTL_URL = https://test.intlgame.com
GAME_ID = {INTL_GAME_ID}
SDK_KEY = {INTL_SDK_KEY}
[INTL Log]
LOG_LEVEL = 1
LOG_CONSOLE_OUTPUT_ENABLE = 1
LOG_FILE_OUTPUT_ENABLE = 1
LOG_ENCRYPT_ENABLE = 0
LOG_COMPRESS_ENABLE = 0
[Android LifeCycle]
LIFECYCLE = Google
[Google]
GOOGLE_CLIENT_KEY_ANDROID = {INTL_GOOGLE_CLIENT_KEY}

将 SDK 后端环境设置为 INTL_URL = https://test.intlgame.com。
将 {INTL_GAME_ID} 和 {INTL_SDK_KEY} 替换为 Player Network 控制台分配的 GAME_ID 和 SDK_KEY 的值。
设置 LOG_LEVEL = 1、LOG_CONSOLE_OUTPUT_ENABLE = 1、LOG_FILE_OUTPUT_ENABLE = 1、LOG_ENCRYPT_ENABLE = 0 和 LOG_COMPRESS_ENABLE = 0，以便在不加密或压缩输出的情况下输出控制台日志和日志文件。
在 LIFECYCLE 中添加 Google。有关更多信息，请参见 SDK 环境。
将 {INTL_GOOGLE_CLIENT_KEY} 替换为 Web 客户端密钥。
这是 API OAuth 配置过程中 Credentials 部分中网络应用的客户端 ID，在 API OAuth 2.5 配置过程中也称为 Server Client ID。

在 gradle 文件中定义 manifestPlaceholders，将 {INTL_GOOGLE_APP_ID} 替换为 Google App ID。

Unity
Unreal Engine

mainTemplate.gradle
android {
    defaultConfig {
      manifestPlaceholders = ["GOOGLE_APPID":"{INTL_GOOGLE_APP_ID}"]
    }
}

note

对于 Player Network SDK V1.17 及更高版本，请编辑 INTLConfig_APL.xml。

对于 Player Network SDK V1.16.04 及更早版本，请编辑 INTLCore_UPL.xml。

<buildGradleAdditions>
    <insert>
    <![CDATA[
    android{
        defaultConfig {
            manifestPlaceholders = ["GOOGLE_APPID":"{INTL_GOOGLE_APP_ID}"]
        }
    }]]>
    </insert>
</buildGradleAdditions>

步骤2：添加 Google 登录

所有 Google 操作都需要连接到 Google 服务。

自动登录 (AuthLogin)

在自动登录期间，设备可能无法连接到 Google 服务。因此推荐在默认情况下，让 Player Network SDK 在自动登录时连接 Google 服务。（游戏团队可在 INTLConfig 配置文件的 Google渠道配置 部分配置配置 GOOGLE_LOGOUT_NEED_CONNECT 字段来禁止此连接。）

返回代码	返回值	错误描述
SERVICE_MISSING	1	设备上的 GMS 不可用。
SERVICE_VERSION_UPDATE_REQUIRED	2	已安装的 GMS 版本已过期。
SERVICE_DISABLED	3	GMS 已禁用。
SERVICE_INVALID	9	安装的 GMS 版本不正确。
SERVICE_UPDATING	18	设备上的 GMS 正在更新。

// Add callbacks
public void AddAuthObserver()
{
    INTLAPI.AddAuthResultObserver(OnAuthResultEvent);
}

// Remove callbacks
public void RemoveAuthObserver()
{
    INTLAPI.RemoveAuthResultObserver(OnAuthResultEvent);
}

// Process the INTLAuthResult callback
public void OnAuthResultEvent(INTLAuthResult AuthResult)
{
    Debug.Log($"MethodID: {AuthResult.MethodId}");
    
    string methodTag = "";
    switch (AuthResult.MethodId)
    {
        case (int)INTLMethodID.INTL_AUTH_LOGIN:
            methodTag = "Login";
            break;
        case (int)INTLMethodID.INTL_AUTH_BIND:
            methodTag = "Bind";
            break;
        case (int)INTLMethodID.INTL_AUTH_AUTOLOGIN:
            methodTag = "AutoLogin";
            break;
        case (int)INTLMethodID.INTL_AUTH_QUERY_USER_INFO:
            methodTag = "QueryUserInfo";
            break;
        case (int)INTLMethodID.INTL_AUTH_GET_AUTH_RESULT:
            methodTag = "GetAuthResult";
            break;
    }
}

C++ Event Handling (above v1.15)

//configure callback
FINTLAuthEvent authEvent;
authEvent.AddUObject(this, &OnAuthResult_Implementation);
UINTLSDKAPI::SetAuthResultObserver(authEvent);
// Remove callbacks
UINTLSDKAPI::GetAuthResultObserver().Clear();

void OnAuthResult_Implementation(FINTLAuthResult ret)
{ 
    UE_LOG(LogTemp, Warning, TEXT("MethodID: %d"), ret.MethodId);
}

Unreal Event Handling

void OnAuthResult_Implementation(FINTLAuthResult ret)
{ 
    UE_LOG(LogTemp, Warning, TEXT("MethodID: %d"), ret.MethodId);
}

调用 AutoLogin 接口自动登录。
- Unity
- Unreal Engine
INTLAPI.AutoLogin();
UINTLSDKAPI::AutoLogin();

在自动登录失败时调用 Login 接口使玩家手动登录。

Unity
Unreal Engine

INTLAPI.Login(INTLChannel.Google); 

UINTLSDKAPI::Login(EINTLLoginChannel::kChannelGoogle); 

与游戏后台同步客户端身份验证状态，等待最终验证结果。

[可选] 设置 email 权限

要在 Google 登录时获取玩家邮箱需先设置对应权限，开启后将在 AuthResult 的 ChannelInfo 中返回 email。

基于合规考虑，可针对特定来源对返回的 email 做 mask 处理，如有需求请联系 Player Network 助手打开。
可在后台流水日志中上报 hash 后的 base64(sha256(email))，如有需求请联系 Player Network 助手打开。
可用于验证玩家信息或绑定列表是否包含 email 信息，如有需求请联系 Player Network 助手打开。

在 Player Network 控制台开启 email 返回功能，将 return_email 设置为 YES，详细步骤请参见第三方渠道配置。

步骤3：验收登录功能

在 Player Network SDK 日志中搜索关键字 "AuthResult" 确认渠道名称和 OpenID 是否正确返回。如果正确，则表明集成配置成功，登录功能已成功添加。

如果接入过程中遇到问题，请参见常见问题。

步骤4：发布游戏

在准备发布正式版本之前，请使用 Android App Bundle 创建一个测试版本。

发布 Beta 版的好处是用户可以从 Google play 下载，但没有添加评论的权限。为用户提交反馈设置了特定的渠道。

创建正式发布版本

进入 Google Play Console。
在左侧导航栏中，选择 Release > Production。
按照说明创建生产版本。

图片：Google beta testing

更改发布状态

caution

如果用户不释放应用，验证可能会失败。

进入 Google 云端平台的 OAuth 同意界面页面。
将 Publishing status 更改为 PUBLISH APP。

图片：Google app release

使用 APK 测试谷歌登录

更多信息，请参见使用 APK 测试谷歌登录。

使用 Google Play Games Services 同步登录态

Google Play Games Services（GooglePGS）支持 PGS 登录、跨设备登录态同步，以及 PGS 成就等功能。推荐需要在 Android 设备与 Google Play 游戏电脑版模拟器之间同步登录态，或需要使用 PGS 成就功能的游戏接入。

接入 GooglePGS 需要集成 INTLGooglePGS 插件。虽然 GooglePGS 可与任意登录渠道配合使用，但通常与 INTLGoogle 搭配使用——跨设备同步功能是为 Google 生态设计的，需要 Android 设备和 Google Play 游戏电脑版模拟器登录同一个 Google 账号。

步骤1：为 GooglePGS 配置 SDK

在项目的 INTLConfig.ini 文件中，添加以下配置：
INTLConfig.ini
```
[Android LifeCycle]
LIFECYCLE = GooglePGS
[GooglePGS]
GOOGLEPGS_SERVER_PROJECT_ID = {INTL_GOOGLEPGS_SERVER_PROJECT_ID}
GOOGLEPGS_ENABLE_PGS = 1
GOOGLEPGS_ENABLE_SYNC = 0
```
- 将 {INTL_GOOGLEPGS_SERVER_PROJECT_ID} 替换为 Web 客户端密钥。
  这是 API OAuth 配置过程中 Credentials 部分中网络应用的客户端 ID，在 API OAuth 2.5 配置过程中也称为 server client ID。
- GOOGLEPGS_ENABLE_PGS 控制客户端侧 PGS 流程是否开启，包括 PGS 初始化、登录和欢迎气泡。设置 GOOGLEPGS_ENABLE_PGS = 1 为启用。
note
从 V1.31 版本开始，GOOGLEPGS_ENABLE_PGS 仅控制客户端侧 PGS 流程。后台同步行为现在由 GOOGLEPGS_ENABLE_SYNC 单独控制。
- GOOGLEPGS_ENABLE_SYNC 控制 SDK 是否将玩家的 OpenID 与 PGS Player ID 同步到 Player Network 后台进行绑定。此绑定可实现基于 PGS 的跨设备自动登录——当玩家在设备 A 上登录后，设备 B 可以通过 PGS Player ID 自动找到关联的 OpenID。设置 GOOGLEPGS_ENABLE_SYNC = 1 为启用，默认为 0（禁用）。
tip
如果您的游戏不需要通过 PGS 实现跨设备登录恢复，可以保持 GOOGLEPGS_ENABLE_SYNC = 0。对于未在 Player Network 管理端配置独立 PGS 渠道的游戏，建议使用此设置。

gradle 文件中定义 manifestPlaceholders，将 {INTL_GOOGLEPGS_APPID} 替换为 Google App ID。

Unity
Unreal Engine

mainTemplate.gradle
android {
    defaultConfig {
      manifestPlaceholders = ["GOOGLEPGS_APPID":"{INTL_GOOGLEPGS_APPID}"]
    }
}

note

对于 Player Network SDK V1.17 及更高版本，请编辑 INTLConfig_APL.xml。

对于 Player Network SDK V1.16.04 及更早版本，请编辑 INTLCore_UPL.xml。

<buildGradleAdditions>
    <insert>
    <![CDATA[
    android{
        defaultConfig {
            manifestPlaceholders = ["GOOGLEPGS_APPID":"{INTL_GOOGLEPGS_APPID}"]
        }
    }]]>
    </insert>
</buildGradleAdditions>

步骤2：在 Google Play 游戏电脑版上，使用 `AutoLogin` 获取登录态

当玩家在 Android 设备上通过任意渠道（如 Google）登录后，即可通过 GooglePGS 将登录态同步到 Google Play 游戏电脑版模拟器上。Android 设备与 PC 模拟器需要登录同一个 Google 账号。

note

此步骤需要在步骤1中设置 GOOGLEPGS_ENABLE_SYNC = 1。如果未启用，OpenID 与 PGS Player ID 的绑定关系不会被创建，跨设备自动登录将无法生效。

Unity
Unreal Engine

INTLAPI.AutoLogin();

UINTLSDKAPI::AutoLogin();

[可选] 步骤3：手动触发 PGS 登录

通过其他渠道（如 Google）成功登录后，SDK 会自动在后台触发一次非强制 PGS 登录。在此自动流程中，SDK 会初始化 PGS 并展示 PGS 欢迎弹窗，然后检查玩家的 PGS 认证状态：

如果已认证：SDK 继续请求服务端授权码，用于 PGS 身份绑定。
如果未认证：SDK 静默跳过 PGS 登录，不会向玩家展示登录界面。

note

在设备上有 Google 账号的情况下，应用首次启动时，PGS v2 可能会展示登录或创建档案的提示，这是 PGS 平台自身的引导流程。此提示由 PGS 初始化（PlayGamesSdk.initialize()）触发，而非 SDK 的 signIn() 调用，不受 SDK 控制。在后续启动中，PGS 会静默认证（如果玩家之前已完成登录）或保持未认证状态而不展示任何界面。如果设备上没有 Google 账号，即使首次启动也不会出现此提示。

如果需要从游戏侧显式触发 PGS 登录（例如让玩家关联 PGS 身份），可以调用 ActivatePGSService 接口。与自动流程不同，此接口为强制登录调用。此接口仅支持 Android。调用时，SDK 将：

执行前置检查：验证 GOOGLEPGS_ENABLE_PGS = 1、Activity 有效、Google Play Services 可用。如果任一检查失败，将通过认证结果回调返回错误。
初始化 PGS 并检查玩家是否已通过 PGS 认证：
- 如果已认证：SDK 直接请求服务端授权码，用于 PGS 身份绑定。
- 如果未认证：由于这是强制登录调用，SDK 会调用 signIn() 向玩家展示 Google PGS 登录界面。如果玩家成功完成登录，SDK 继续请求授权码。如果玩家关闭界面或登录失败，将通过认证结果回调返回错误。

Unity
Unreal Engine

INTLAPI.ActivatePGSService();

UINTLSDKAPI::ActivatePGSService();

GooglePGS 配置参考

配置项	默认值	说明
`GOOGLEPGS_SERVER_PROJECT_ID`	—	Google Cloud Console OAuth 凭证中的 Web 客户端 ID（server client ID）。必填。
`GOOGLEPGS_ENABLE_PGS`	`0`	启用客户端侧 PGS 流程（初始化、登录、欢迎气泡）。
`GOOGLEPGS_ENABLE_SYNC`	`0`	将玩家的 OpenID 与 PGS Player ID 同步到 Player Network 后台进行绑定，以实现跨设备自动登录。

Google PGS 成就系统

Player Network SDK 提供了成就模块，集成了 Google Play Games Services 成就功能。游戏可以通过此模块解锁成就、增加进度以及展示原生成就界面。

info

成就模块目前仅支持 Android（GooglePGS）。iOS、Windows 及其他成就服务的支持将在后续版本中提供。

前提条件

完成上述 GooglePGS 配置，并设置 GOOGLEPGS_ENABLE_PGS = 1。
在 Google Play Console 的 Play Games Services > Setup and management > Achievements 中配置成就。
调用任何成就接口前，PGS 必须已认证。当 GOOGLEPGS_ENABLE_PGS = 1 时，SDK 会在成功登录后自动认证 PGS，也可以通过 ActivatePGSService 手动触发。

步骤1：注册成就回调

注册回调以接收成就操作结果。

Unity
Unreal Engine

// 添加成就回调
INTLAPI.AddAchievementResultObserver(OnAchievementResult);

// 移除成就回调
INTLAPI.RemoveAchievementResultObserver(OnAchievementResult);

// 处理成就结果
public void OnAchievementResult(INTLAchievementResult ret)
{
    Debug.Log($"Achievement MethodID: {ret.MethodId}, RetCode: {ret.RetCode}");
}

// 注册成就回调
FINTLAchievementEvent achievementObserver;
achievementObserver.AddUObject(this, &UMyClass::OnAchievementResult);
UINTLSDKAPI::SetAchievementResultObserver(achievementObserver);

// 移除成就回调
UINTLSDKAPI::GetAchievementResultObserver().Clear();

void UMyClass::OnAchievementResult(FINTLAchievementResult ret)
{
    UE_LOG(LogTemp, Log, TEXT("Achievement MethodID: %d, RetCode: %d"), ret.MethodId, ret.RetCode);
}

步骤2：解锁成就

通过成就 ID 解锁一个标准（非增量）成就。

Unity
Unreal Engine

INTLAPI.UnlockAchievement("GooglePGS", "achievement_id_here");

UINTLSDKAPI::UnlockAchievement(TEXT("GooglePGS"), TEXT("achievement_id_here"), TEXT("{}"));

步骤3：增加成就进度

对于增量成就，按指定步数增加进度。

Unity
Unreal Engine

INTLAPI.IncrementAchievement("GooglePGS", "achievement_id_here", 1);

UINTLSDKAPI::IncrementAchievement(TEXT("GooglePGS"), TEXT("achievement_id_here"), 1, TEXT("{}"));

步骤4：展示成就界面

展示 Google Play Games 原生成就界面。

Unity
Unreal Engine

INTLAPI.ShowAchievementsUI("GooglePGS");

UINTLSDKAPI::ShowAchievementsUI(TEXT("GooglePGS"), TEXT("{}"));

成就接口参考

接口	参数	说明
`UnlockAchievement`	`channel`、`achievementId`、`extraJson`（可选）	解锁一个标准成就。
`IncrementAchievement`	`channel`、`achievementId`、`numSteps`、`extraJson`（可选）	增加增量成就的进度。
`ShowAchievementsUI`	`channel`、`extraJson`（可选）	展示原生成就界面。
`AddAchievementResultObserver`	`callback`	注册成就结果回调。
`RemoveAchievementResultObserver`	`callback`	移除已注册的成就结果回调。

成就结果数据

INTLAchievementResult（Unity）/ FINTLAchievementResult（UE）包含：

字段	类型	说明
`MethodId`	`int`	触发此结果的方法（2701=解锁，2702=增加进度，2703=展示界面）。
`RetCode`	`int`	结果码。`0` 表示成功。
`SubRetCode`	`int`	二级结果码（V1.28 起可用）。
`RetMsg`	`string`	结果消息。
`ThirdCode`	`int`	平台特定错误码。`11002` = NOT_AUTHENTICATED（PGS 未登录）。
`ThirdMsg`	`string`	外部平台返回的消息。
`ExtraJson`	`string`	预留字段（JSON 格式）。
`Platform`	`string`	成就提供方名称，如 `"GooglePGS"`。
`SeqId`	`string`	请求的序列 ID。
`AchievementList`	`list`	`AchievementInfo` 对象列表。请参见下方说明。

note

在当前的 GooglePGS 实现中，所有成就操作（UnlockAchievement、IncrementAchievement、ShowAchievementsUI）返回的 AchievementList 始终为空。此字段可以安全忽略。未来 SDK 版本添加成就查询功能时可能会填充此字段——这适用于所有渠道的成就模块，而非仅限于 GooglePGS。建议使用空值检查（if (achievementRet.AchievementList != null)）作为防御性编程模式。

每个 AchievementInfo 包含：

字段	类型	说明
`AchievementId`	`string`	成就标识符。
`Name`	`string`	成就显示名称。
`Description`	`string`	成就描述。
`CurrentSteps`	`int`	当前进度（增量成就）。
`TotalSteps`	`int`	所需总步数（增量成就）。
`Status`	`int`	成就状态（已解锁/进行中）。
`UnlockTime`	`int`	成就解锁时间戳。

前提条件​

步骤1：为 Google 登录配置 SDK​

步骤2：添加 Google 登录​

自动登录 (AuthLogin)​

登录​

[可选] 设置 email 权限​

步骤3：验收登录功能​

步骤4：发布游戏​

使用 Google Play Games Services 同步登录态​

步骤1：为 GooglePGS 配置 SDK​

步骤2：在 Google Play 游戏电脑版上，使用 AutoLogin 获取登录态​

[可选] 步骤3：手动触发 PGS 登录​

GooglePGS 配置参考​

Google PGS 成就系统​

前提条件​

步骤1：注册成就回调​

步骤2：解锁成就​

步骤3：增加成就进度​

步骤4：展示成就界面​

成就接口参考​

成就结果数据​

前提条件

步骤1：为 Google 登录配置 SDK

步骤2：添加 Google 登录

自动登录 (AuthLogin)

登录

[可选] 设置 email 权限

步骤3：验收登录功能

步骤4：发布游戏

使用 Google Play Games Services 同步登录态

步骤1：为 GooglePGS 配置 SDK

步骤2：在 Google Play 游戏电脑版上，使用 `AutoLogin` 获取登录态

[可选] 步骤3：手动触发 PGS 登录

GooglePGS 配置参考

Google PGS 成就系统

前提条件

步骤1：注册成就回调

步骤2：解锁成就

步骤3：增加成就进度

步骤4：展示成就界面

成就接口参考

成就结果数据