Android

说明

在 Android 设备上卸载游戏后，Garena 游客账号将丢失。建议游戏鼓励游客玩家尽快将游客账号与平台账号绑定，以避免游客账号意外丢失，并增强游戏的社交属性。

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

前提条件

1. 设置 Garena 应用

联系 Garena 团队激活应用程序并获取应用程序 ID 和其他相关信息。

Player Network SDK V1.24 及之后版本，还需联系 Garena 团队获取 Garena SDK 相关 Maven 仓库的 Garena_Username 和 Garena_Password。

要使用 Garena 的平台账号绑定，请请求 Garena 启用 APP_PLATFORM_BIND。

步骤1：为 Garena 登录配置 SDK

打开 INTLConfig.ini 文件。
INTLConfig.ini
```
[INTL environment]
# WARNING: You should change this URL to the production environment when you release your game.
INTL_URL = https://intlsdk-new-test.iegg.garena.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 = Garena
[Garena Channel Configurations]
GARENA_APP_SDK_ASSIGN_ID = {INTL_GARENA_APP_SDK_ASSIGN_ID}
GARENA_APP_SDK_KEY = {INTL_APP_KEY}
```
- 将 Player Network SDK 鉴权域名设置为 INTL_URL = https://intlsdk-new-test.iegg.garena.com，可联系 Garena 团队了解详情并获取正式环境 URL。
- 将 {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 中添加 Garena。有关更多信息，请参见 SDK 环境。
- 将 {INTL_GARENA_APP_SDK_ASSIGN_ID} 替换为已注册的 Garena App ID。
- 将 {INTL_APP_KEY} 替换为已注册的 Garena App Key。

在 gradle 文件中定义 manifestPlaceholders，将 {INTL_GARENA_APP_SDK_ASSIGN_ID}、{INTL_FACEBOOK_APP_ID} 和 {INTL_GOOGLE_CLIENT_ID} 替换为应用程序的相应值。

接入 Player Network SDK V1.22 及之后版本还需将 {INTL_FACEBOOK_CLIENT_TOKEN} 替换为 FACEBOOK_CLIENT_TOKEN 的值。
接入 Player Network SDK V1.24 及之后版本还需将 {INTL_GARENA_MAVEN_USERNAME} 和 {INTL_GARENA_MAVEN_PASSWORD} 替换为 Garena_Username 和 Garena_Password 的值。

Unity
Unreal Engine

注意

对于 Unity 2022 版本，请编辑 settingsTemplate.gradle。

对于 Unity 2019/2020/2021 版本，请编辑 baseProjectTemplate.gradle。

对于 Unity 2018 及更早版本，请编辑 mainTemplate.gradle。

android {
    defaultConfig {
        manifestPlaceholders = [
            "GARENA_APP_ID":"{INTL_GARENA_APP_SDK_ASSIGN_ID}", 
            "FACEBOOK_APPID":"{INTL_FACEBOOK_APP_ID}",
            "GOOGLE_CLIENT_ID":"{INTL_GOOGLE_CLIENT_KEY_ANDROID}",
            "FACEBOOK_CLIENT_TOKEN":"{INTL_FACEBOOK_CLIENT_TOKEN}",     // V1.22 新增
            "Garena_Username":"{INTL_GARENA_MAVEN_USERNAME}",           // V1.24 新增
            "Garena_Password":"{INTL_GARENA_MAVEN_PASSWORD}",           // V1.24 新增
        ]
    }
}

注意

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

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

<buildGradleAdditions>
    <insert>
    <![CDATA[
    android{
        defaultConfig {
            manifestPlaceholders += [
                "GARENA_APP_ID":"{INTL_GARENA_APP_SDK_ASSIGN_ID}", 
                "FACEBOOK_APPID":"{INTL_FACEBOOK_APP_ID}",
                "GOOGLE_CLIENT_ID":"{INTL_GOOGLE_CLIENT_KEY_ANDROID}",
                "FACEBOOK_CLIENT_TOKEN":"{INTL_FACEBOOK_CLIENT_TOKEN}",     // V1.22 新增
                "Garena_Username":"{INTL_GARENA_MAVEN_USERNAME}",           // V1.24 新增
                "Garena_Password":"{INTL_GARENA_MAVEN_PASSWORD}",           // V1.24 新增
            ]
        }
    }]]>
    </insert>
</buildGradleAdditions>

根据以下代码在 AndroidManifest.xml 文件中声明权限。

警告

WRITE_EXTERNAL_STORAGE 是一个敏感权限。

AndroidManifest.xml
<manifest ... >
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.READ_MEDIA_IMAGES" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
...
</manifest>

对于 Unreal Engine，将 Player Network SDK V1.13 及更高版本的 Garena 计费存储库更新至 4.0.0
1. 如果使用 Unreal Engine 4.25、
  1. 下载 GooglePlayStoreHelper.java。然后替换 {UE_PATH}/Engine/Plugins/Online/Android/OnlineSubsystemGooglePlay/Source/Java/com/epicgames/ue4/GooglePlayStoreHelper.java 文件。
  2. 下载 OnlineSubsystemGooglePlay_UPL.xml。然后替换 {UE_PATH}/Engine/Plugins/Online/Android/OnlineSubsystemGooglePlay/Source/OnlineSubsystemGooglePlay_UPL.xml 文件。
2. 如果使用 Unreal Engine 4.26 或更高版本、
  1. 下载 GooglePlayStoreHelper.java。然后替换 {UE_PATH}/Engine/Plugins/Online/Android/OnlineSubsystemGooglePlay/Source/Java/BillingApiV2/com/epicgames/ue4/GooglePlayStoreHelper.java 文件。
  2. 将{UE_PATH}/Engine/Plugins/Online/Android/OnlineSubsystemGooglePlay/Source/OnlineSubsystemGooglePlay_UPL.xml中的计费存储库版本修改为4.0.0。

步骤2：添加 Garena 登录

注册登录相关回调。

Unity
Unreal Engine

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

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

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

C++ 事件处理法（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 事件处理法

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

调用 AutoLogin 接口自动登录。
- Unity
- Unreal Engine
INTLAPI.AutoLogin();
UINTLSDKAPI::AutoLogin();
在自动登录失败时调用 Login 接口，使玩家手动登录。
注意
目前，Player Network SDK 支持登录的 Android Garena 子渠道包括 Guest、Garena、Facebook、Google。通过检查 AuthResult 的 ExtraJson 字段中返回的子渠道名称查看当前用于登录的子渠道。例如，{"subChannel":"Facebook"}".
登录 Garena 的 Facebook 子渠道：
- Unity
- Unreal Engine
INTLAPI.Login(INTLChannel.Garena, "", "{\"subChannel\":\"Facebook\"}");
UINTLSDKAPI::Login(EINTLLoginChannel::kChannelGarena, "", "{\"subChannel\":\"Facebook\"}");
- 如果已安装应用程序，则打开应用程序登录，否则打开网页登录。
- Garena 登录 permission 参数与其他渠道不同。用户需要输入字符串格式的数字。例如，"2" 或 "4"。权限定义如下：
与游戏后台同步客户端身份验证状态，等待最终验证结果。

步骤3：验收登录功能

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

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

绑定

警告

Android 卸载游戏后会丢失 Garena 游客账号。建议游戏们鼓励游客玩家尽早绑定到平台账号以避免账号意外丢失，以及增强社交属性。

注意

由于 Garena 的渠道特性：

如果之前已使用过 Facebook 登录，则不能将其用作 Garena 登录的子渠道。否则，将返回错误代码 1013。
成功绑定 Garena 账号后，不能再次绑定。

调用 Bind 接口时，会打开子渠道的应用程序（或网页）以执行登录验证。认证成功后，Player Network SDK 会将子渠道的账号与游客账号绑定。

Unity
Unreal Engine

// Log in as guest
INTLAPI.Login(INTLChannel.Garena, "", "{\"subChannel\":\"Guest\"}");
// Bind Logic
INTLAPI.Bind(INTLChannel.Garena, "", "{\"subChannel\":\"Facebook\"}");

// Log in as guest
UINTLSDKAPI::Login(EINTLLoginChannel::kChannelGarena, "", "{\"subChannel\":\"Guest\"}");
// Bind Logic
UINTLSDKAPI::Bind(EINTLLoginChannel::kChannelGarena, "", "{\"subChannel\":\"Facebook\"}");

注意

如果将游客账号绑定到 Garena 失败，游戏必须再次调用 Garena 的游客登录。

说明

调用 Bind 接口后，无论绑定结果如何，Garena SDK 的会话都会被设置为新绑定的渠道（带游客登录状态）。如果再次调用 Bind 接口，绑定将因会话验证失败而失败。因此，建议再次调用游客登录以返回正常的游客登录状态。

如果您在通过 Garena 登录时遇到困难，请参见 Garena 常见问题。

前提条件​

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

步骤2：添加 Garena 登录​

步骤3：验收登录功能​

绑定​

前提条件

步骤1：为 Garena 登录配置 SDK

步骤2：添加 Garena 登录

步骤3：验收登录功能

绑定