Android

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

前提条件

1. 在 Facebook 开发者平台上配置应用

1. 注册账号

在为应用配置平台之前，请注册 Facebook 开发者账号并在 Facebook App Dashboard 创建应用。

1. 在 Facebook 注册账号并根据提示完成账号认证（Email 或手机认证）。

2. 在 Meta for Developers 激活开发者账号。

   

3. 同意协议并继续。

   

4. 完成手机验证。

   

5. 确认邮箱。

   

6. 完成注册。

   

7. 在 Meta for Developers 将 Facebook SDK 添加到项目。

2. 创建应用

1. 在右上角点击 Create App。

   

2. 填写基本信息：

   • App name - INTLConfig.ini 配置文件中的 FACEBOOK_DISPLAYNAME。
   • App contact email - 主要联系邮箱，用于接收由 Facebook 方发送，关于该应用的各种通知。

   

3. 应用类型选择为 Authenticate and request data from users with Facebook Login。

   

4. 选择 Business，如果未显示则请继续下一步。

   

5. 同意并继续。

   

6. 检查概览, 点击 Go to Dashboard 即可完成 app 创建。

   

3. 配置应用

警告

按照 Facebook 规范输入隐私协议 URL、用户数据删除和服务条款 URL。如果您不遵守 Facebook 规范，Facebook 可能会在您的应用程序发布后禁用您的应用程序。

注意

已提交到 Facebook 的应用可以继续使用 Facebook Login For Gaming，未提交的新 App 只能使用 Facebook Login。更多详情，请参见 Facebook Login For Gaming。

1. 在左侧导航栏中，点击 App Settings > Basic 查看应用程序的基本信息，如 App ID 和 App secret。

   

2. 在 Privacy Policy URL 字段中，输入隐私协议的网址。

3. 在 User Data Deletion 字段中，选择数据删除说明 URL，并根据用户的数据删除说明输入网址。

4. 在 Terms of Service 字段中，输入服务条款网页的 URL。

5. 点击 Add Platform，选择 Android 添加 Android 应用程序。

   

6. 直接输入配置，或点击平台配置界面右上角的 Quick Start，根据指南设置配置。

   注意

   关于 Key Hashes 生成方法，请参见 Facebook 官方指南。

   

7. 点击 Save Changes 保存配置。

配置 Facebook 登录

1. 在 Facebook App Dashboard，点击 Use cases > Customize。
   
2. 在 Facebook Login 下选择 Settings。
3. 在 Valid OAuth Redirect URIs，填写 https://common-web.intlgame.com/jssdk/facebooklogincallback.html 和 https://test-common-web.intlgame.com/jssdk/facebooklogincallback.html。
4. 打开 Embedded Browser OAuth Login。
   
5. 在页面底部点击 Save changes 保存配置。

4. 添加测试人员权限

在应用发布之前，只有测试用户或被添加到权限列表中的用户才能访问 Facebook 的功能。

1. 在 Facebook App Dashboard 中，点击 Roles。
2. 点击 Add Administrators/Add Developers/Add Testers 以添加各个角色。

5. 完成 Facebook 商务认证

某些 Meta 技术或功能需要通过 Meta 商务认证后才可以使用。如需商务认证，请联系 Player Network 助手。

2. 获取 Player Network 控制台登录账号。
3. 为游戏创建新项目，或加入已有项目。
4. 下载 SDK。
5. 接入 SDK。
6. 在 Player Network 控制台添加 Facebook 为业务的登录鉴权方式。

步骤1：为 Facebook 登录配置 SDK

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

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

2. 打开项目的 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 = Facebook
   [Facebook]
   FACEBOOK_APP_ID = {INTL_FACEBOOK_APP_ID}
   FACEBOOK_DISPLAYNAME = {INTL_APP_NAME} 
   • 将 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 中添加 Facebook。有关更多信息，请参见 SDK 环境。
   • 将 {INTL_FACEBOOK_APP_ID} 替换为 Facebook App ID。
   • 将 {INTL_APP_NAME} 替换为 Facebook 应用程序的名称。

3. 在 gradle 文件中定义 manifestPlaceholders，将 {INTL_FACEBOOK_APP_ID} 替换为 Facebook App ID。

   Unity

   mainTemplate.gradle

   android {
       defaultConfig {
           manifestPlaceholders = ["FACEBOOK_APPID":"{INTL_FACEBOOK_APP_ID}"]
       }
   }

   Unreal Engine

   注意

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

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

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

4. 配置 ClientToken。可在 Facebook 开发者平台进入 App Dashboard，选择 App settings/Advanced/Client token 获取 ClientToken。更多说明，参见 Android 版 Facebook SDK 入门指南。

   

   注意

   为 Facebook 渠道添加了 ClientToken 配置，以解决短时间内调用 fb graph api 次数过多时应用程序失败的问题。 此功能在 V1.19.03 及更高版本中生效。V1.19.02 及更早版本不需要以下配置。

   Unity

   在 INTLConfig.ini 中添加 ClientToken 配置。

   FACEBOOK_CLIENT_TOKEN = CLIENT-TOKEN

   在 projmods 文件中添加 ClientToken 配置。

   "FacebookClientToken":"CLIENT-TOKEN"

   Unreal Engine

   在 INTLConfig.ini 中添加 ClientToken 配置。

   FACEBOOK_CLIENT_TOKEN = CLIENT-TOKEN

   在 gradle 文件中添加 ClientToken 配置。

   "FACEBOOK_CLIENT_TOKEN"  : "CLIENT-TOKEN"

步骤2：添加 Facebook 登录

对于 Android，Player Network 会在拉起网页登录之前检查应用程序登录状态。

• 如果安装了 Facebook 应用程序，Player Network 会打开 Facebook 应用程序进行登录。
• 如果未安装 Facebook 应用程序，Player Network 会打开网页客户端进行登录。

Player Network 还支持 “使用 Facebook 登录 Gaming 平台”。更多信息，请参见 Facebook 官方文档中的 技术实现 部分。

1. 注册登录相关回调。

   Unity

   // 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";
       }
   }

   Unreal Engine

   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);
   }

2. 调用 AutoLogin 接口自动登录。

   Unity

   INTLAPI.AutoLogin();

   Unreal Engine

   UINTLSDKAPI::AutoLogin();

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

   • 常规 Facebook Login

     Unity

     // taking Facebook as example
     INTLAPI.Login(INTLChannel.Facebook);

     Unreal Engine

     // taking Facebook as example
     UINTLSDKAPI::Login(EINTLLoginChannel::kChannelFacebook);

   • 使用 Facebook 登录 Gaming 平台

     使用以下参数调用 Login 接口获取 Facebook 社交头像。更多信息，请参见 请求用户的头像。

     Unity

     //在原来的 permissions 字符串里，添加一个 `gaming_user_picture` 权限，类似这样：`"email,public_profile,gaming_user_picture"`
     public static void Login(string channel, string permissions = "gaming_profile,gaming_user_picture", string extraJson = "{}");

     Unreal Engine

     //在原来的 permissions 字符串里，添加一个 `gaming_user_picture` 权限，类似这样：`"email,public_profile,gaming_user_picture"`
     UFUNCTION(BlueprintCallable, Category = "INTLSDKAPI")
     static bool Login(
     const EINTLLoginChannel Channel,
     const FString Permissions = "gaming_profile,gaming_user_picture",
     const FString ExtraJson = "{}");

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

[可选] 设置 email 权限

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

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

1. 在 Meta for Developers 配置 email 权限。email 权限需要有 高级访问级别，才能让所有应用都能获取到玩家的 email。

   

2. 调用 Login 接口时，需要在 permissions 参数中添加 email 权限。调用 Login 接口时如果 permissions 参数没有传入或者为空时，Player Network SDK 将会加上 email 权限。

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

步骤3：验收登录功能

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

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