iOS

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

前提条件

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

1. 注册账号

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

在 Facebook 注册账号并根据提示完成账号认证（Email 或手机认证）。
在 Meta for Developers 激活开发者账号。

图片: Activate a Facebook developer account

同意协议并继续。

图片: Consent to the agreement and continue

完成手机验证。

图片: Mobile phone verification

确认邮箱。

图片: Mobile phone verification

完成注册。

图片: Complete registration

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

2. 创建应用

在右上角点击 Create App。

图片: Create an app

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

图片: Gaming app

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

图片: Gaming app

填写基本信息。
INTLConfig.ini 配置文件中的 SDK 的所有配置应为此处的 App name。

Images: Enter basic information

同意并继续。

Images: Enter basic information

3. 配置应用

警告

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

注意

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

在左侧导航栏中，点击 App Settings > Basic 查看应用程序的基本信息，如 App ID 和 App secret。
在 Privacy Policy URL 字段中，输入隐私协议的网址。
在 User Data Deletion 字段中，选择数据删除说明 URL，并根据用户的数据删除说明输入网址。
在 Terms of Service 字段中，输入服务条款网页的 URL。
点击 Add Platform，选择 iOS 添加 iOS 应用程序。
直接输入配置，或点击平台配置界面右上角的 Quick Start，根据指南设置配置。
点击 Save Changes 保存配置。

配置 Facebook 登录

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

4. 添加测试人员权限

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

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

图片：添加测试用户

5. 完成 Facebook 商务认证

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

图片：商务认证

步骤1：为 Facebook 登录配置 SDK

打开 INTLSDK/Scripts/INTLConfig/Editor/Resources/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
[Facebook channel configuration]
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，以便在不加密或压缩输出的情况下输出控制台日志和日志文件。
- 将 {INTL_FACEBOOK_APP_ID} 替换为 Facebook App ID。
- 将 {INTL_APP_NAME} 替换为 Facebook 应用程序的名称。

将 Facebook 添加到 Info.plist 文件中。

Unity
Unreal Engine

在从 Unity 导出 Xcode 项目之前，检查 INTLFacebookKit.projmods 中的预定义值，并将 {Facebook_APP_ID} 替换为 Facebook App ID。

{
    "group": "INTL",
    "Info.plist":{
        "LSApplicationQueriesSchemes":
        [
            "fb-messenger-api",
            "fbshareextension",
            "fbauth2",
            "fb-messenger-share-api",
            "fbapi",
            "fb",
        ],
        "CFBundleURLTypes" :
        [
            {
                "CFBundleTypeRole":"Editor",
                "CFBundleURLName":"Facebook",
                "CFBundleURLSchemes":["fb{Facebook_APP_ID}"]
            }
        ]
    },
}

SDK 1.18 及之后版本
SDK 1.18 之前版本

根据 SDK 版本打开对应的文件进行修改：

V1.24 及之后版本：INTLSDK/Source/INTLFacebook/Libs/iOS/INTLFacebook_UPL.xml
V1.18 至 V1.23：INTLSDK/Source/INTLConfig/Configs/iOS/Plist/INTLFacebook.plist

<key>CFBundleURLSchemes</key>
<array>
    <string>fb{INTL_FACEBOOK_APP_ID}</string>
</array>

业务需到 Unreal Engine > Settings > Project Settings > Platforms > iOS > Extra Plist Data 修改配置，在 PLIST 文件中添加 SDK。

图片：Extra Plist Data

<key>LSApplicationQueriesSchemes</key>
<array>
    <string>fb</string>
    <string>fb-messenger-api</string>
    <string>fbshareextension</string>
    <string>fbauth2</string>
    <string>fb-messenger-share-api</string>
    <string>fbapi</string>
</array>
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>Facebook</string>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>fb{INTL_FACEBOOK_APP_ID}</string>
        </array>
    </dict>
</array>

替换 {INTL_FACEBOOK_APP_ID} 为步骤2 获取的 Facebook App ID。

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

注意
Facebook 渠道新增 ClientToken 配置，解决 app 在短时间内大量调用 fb graph api 会失败的问题。
此功能在 V1.19.03 及更高版本中生效。V1.19.02 及更早版本不需要以下配置。
- Unity
- Unreal Engine
在 intlconfig.ini 文件增加 ClientToken 配置。
FACEBOOK_CLIENT_TOKEN = CLIENT-TOKEN
在 projmods 文件增加 ClientToken 配置。
"FacebookClientToken":"CLIENT-TOKEN"
在 intlconfig.ini 文件增加 ClientToken 配置。
FACEBOOK_CLIENT_TOKEN = CLIENT-TOKEN
在 plist 文件增加 ClientToken 配置。
</array> <key>FacebookAppID</key> <string>APP-ID</string> <key>FacebookClientToken</key> <string>CLIENT-TOKEN</string> <key>FacebookDisplayName</key> <string>APP-NAME</string> </array>

步骤2：添加 Facebook 登录

对于 iOS，Player Network 在登录状态之前检查网页登录状态，调用 Player Network SDK 的 Login 接口进行登录。

如果 Safari 已登录 Facebook，Player Network 会打开网页客户端进行登录。
如果 Safari 没有登录Facebook，Player Network 会检查是否安装了 Facebook 应用程序。
- 如果安装了 Facebook 应用程序，Player Network 就会打开 Facebook 应用程序进行登录。如果玩家取消了应用程序上的登录，他们可以继续在网络客户端上登录。
- 如果未安装 Facebook 应用程序，Player Network 将打开网页客户端进行游戏登录。

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

注册登录相关回调。

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++ 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 接口使玩家手动登录。

常规 Facebook Login

Unity
Unreal Engine

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

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

使用 Facebook 登录 Gaming 平台

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

Unity
Unreal Engine

//在原来的 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 = "{}");

//在原来的 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 = "{}");

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

受限登录

警告

需要 Player Network SDK v1.15。
仅支持 iOS 设备。

Player Network SDK Facebook 支持有限登录。更多信息，请参见 Facebook Website Limited Login。

当有限登录调用登录 API 时，必须传入 extraJson 参数 "{\"login_mode\":1}"。

Unity
Unreal Engine

INTLAPI.Login(INTLChannel.Facebook,"","{\"login_mode\":1}");

UINTLSDKAPI::Login(EINTLLoginChannel::kChannelFacebook,"","{\"login_mode\":1}");

[可选] 设置 email 权限

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

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

在 Meta for Developers 配置 email 权限。email 权限需要有高级访问级别，才能让所有应用都能获取到玩家的 email。
调用 Login 接口时，需要在 permissions 参数中添加 email 权限。调用 Login 接口时如果 permissions 参数没有传入或者为空时，Player Network SDK 将会加上 email 权限。
在 Player Network 控制台开启 email 返回功能，将 return_email 设置为 YES，详细步骤请参见第三方渠道配置。

步骤3：验收登录功能

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

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

前提条件​

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

步骤2：添加 Facebook 登录​

受限登录​

[可选] 设置 email 权限​

步骤3：验收登录功能​