LI PASS 开始接入

从本文开始，跟着指引一步步接入 PlayerNetwork SDK吧！

note

若需人工服务，可以到企业微信咨询 Player Network助手 。

游戏注册&配置

注册和配置游戏，需要登录Player Network Console，详情可参考Player Network Console使用文档。

获取PlayerNetwork SDK

进入PlayerNetwork SDK 下载页面，按需选择对应的引擎和平台，下载PlayerNetwork SDK。详情可参考PlayerNetwork SDK 下载指引文档。

客户端接入

步骤一：在游戏工程中，导入PlayerNetwork SDK

Unity

1、Player Network SDK 接入

引擎版本支持情况

SDK 版本号	支持的 Unity 版本
SDK 1.27 及以后的版本	Unity 2021 ~ Unity 6
SDK 1.24 ~ 1.26	Unity 2021 ~ Unity 2022

Player Network SDK 支持 Android，iOS，Windows 以及 Console 不同平台接入，详情请参考接入文档 Player Network SDK 接入。

2、 拷贝文件到工程中

将 LevelInfinite、INTLSDK、Plugins 和 StreamingAssets/LevelInfinite 文件夹复制到游戏项目的 Assets 目录后，再打开 Unity 工程。

文件夹	说明
LevelInfinite	LI PASS 引擎层代码
INTLSDK	Player Network sdk 引擎层代码
Plugins	LI PASS 平台层库文件
StreamingAssets/LevelInfinite	LI PASS 业务逻辑资源，可热更
Symbols	PlayerNetwork SDK的符号表文件，用于还原堆栈

note

Symbols目录下的文件，需妥善保存，游戏上线后，排查线上问题，有可能需要用到符号表。

导入过程若遇到的问题，可参考文末 可能遇到的问题，或联系 Player Network助手 咨询。

3、 生成 Unity 的 Lua 接口文件

打开 Unity 工程，会自动弹出 生成 C# 导出的 Lua 接口文件，如下图，点击 Generate 即可。

如果没有弹窗，在 Unity 菜单栏，选择 INTLLua > All > Clear 删除，会删除 Assets/LevelInfinite/Runtime/INTLGameNative/Scripts/LuaObject 目录（或手动删除该目录）。
之后会自动弹窗提示生成 Unity 的 Lua 接口。如未弹窗，在 Unity 菜单栏选择 INTL > INTLLua > All > Make 来手动触发弹窗。

可在 Assets/LevelInfinite/Runtime/INTLGameNative/Scripts/LuaObject 目录中查看接口导出文件是否成功生成。

Unreal Engine

1、Player Network SDK 接入

引擎版本支持情况

SDK 版本号	支持的 Unity 版本
SDK 1.26 及以后的版本	UE4.21 ~ UE4.27 & UE5 ~ UE5.5
SDK 1.26 之前版本	UE4.21 ~ UE4.27 & UE5 ~ UE5.4

Player Network SDK 支持 Android，iOS，Windows 以及 Console 不同平台接入，详情请参考接入文档 Player Network SDK 接入。

2、 拷贝文件到工程中

将 LevelInfinite 和 INTLSDK 目录拷贝至游戏工程的 Plugins 目录中。如果项目没有 Plugins 目录，可以手动创建一个。

文件夹	说明
LevelInfinite	LI PASS 引擎层代码&相关依赖库
INTLSDK	Player Network sdk 引擎层代码&相关依赖库
Symbols	PlayerNetwork SDK的符号表文件，用于还原堆栈

note

LevelInfiniteAssetVersion.lua 的文件拓展名为 LUA 而并非 LUAC，是因为里面包含了 LI PASS 的版本号，方便业务同学了解我们的 LI PASS 版本，便于定位问题。

Symbols目录下的文件，需妥善保存，游戏上线后，排查线上问题，有可能需要用到符号表。

3、在游戏工程中添加PlayerNetwork SDK依赖

打开游戏项目的构建文件，即 {项目名}.Build.cs 文件，并按照示例将 LevelInfinite 插件添加为模块的私有依赖：

public INTLSample(ReadOnlyTargetRules Target) : base(Target)
{
    PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

    PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore", "HeadMountedDisplay" });

    // Add the following code
    PrivateDependencyModuleNames.AddRange(new string[] {
            "INTLCore",
            "INTLFoundation",
            "INTLConfig",
            "LevelInfinite"
    });
}

4、 将 LI PASS Lua 资源打进首包

将 LI PASS Lua 资源打进首包，在 Packaging/Additional Non-Asset 选项中添加：

• ../Plugins/LevelInfinite/Content

note

业务需要根据实际存放 LevelInfinite 文件夹的路径进行填写，例如实际存放路径是 ../Plugins/Template/LevelInfinite，则在此需要添加的是 ../Plugins/Template/LevelInfinite/Content。

5、 将 LI PASS uasset 资源打进首包

将 LI PASS uasset 资源打进首包，在 Packaging/Additional Asset 选项中添加： /LevelInfinite

步骤二：配置 INTLConfig.ini 文件

• INTLConfig.ini 文件包含 LI PASS 服务的配置项，是游戏使用LI PASS服务必需的配置文件。
• 在下载 SDK 的时候，INTLConfig.ini 会生成默认的配置，游戏可使用这些配置体验 LI PASS 相关功能。
• 若有修改INTLConfig.ini配置项的需求，可选择使用游戏引擎的可视化配置编辑工具来修改，或直接修改 INTLConfig.ini 文件。

Unity

通过编辑器工具栏 INTL > LI INIConfig Window 打开可视化配置编辑工具。

Unreal Engine

通过编辑器工具栏 LITools > Config Editor 打开可视化配置编辑工具。

有关各配置项的详情，可在编辑器选中选项来自动展示选项的简述，或参见 SDK 的所有配置 查看完整的配置项列表。

[可选] 第三方渠道登录时获取玩家邮箱

note

此项设置属于 Player Network 控制台的 第三方渠道配置，Web 端运营角色将无权限访问，请联系业务完成配置。

要使用 Web 绑定模块的快速绑定功能，需先设置在第三方渠道登录时获取玩家邮箱的权限。

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

以下为支持返回玩家邮箱的第三方渠道：

Apple

note

Apple 获取玩家邮箱需要玩家授权，如果玩家拒绝授权将无法获取到玩家邮箱，详见 Login 接口传入 email 和 fullName。

1. 使用编辑工具，将 email 权限添加到 [Dynamic] 下的 APPLE_LOGIN_PERMISSION。

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

Google

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

Facebook

1. 使用编辑工具，将 email 权限添加到 [Dynamic] 下的 FACEBOOK_LOGIN_PERMISSION。如果 INTLConfig.ini 没有配置 FACEBOOK_LOGIN_PERMISSION，则会自动带上 email 权限。

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

   

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

Twitter

1. 在 Twitter Developer Platform 的 User authentication settings 下，勾选 Request email from users。

   

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

步骤三：初始化 LI PASS

Unity

游戏启动的时候，应调用PNTSDK提供的初始化接口 INTLAPI.InitSDK 和 LevelInfinite.InitLIP 。

• 初始化过程会检查当前资源版本是否有可用的热更资源；
• 若有资源更新，将会自动下载新版资源，然后加载新版资源；
• 资源加载完成后，会触发 LI PASS 事件回调（LIEventObserver）中的 GN_READY 事件，此时LI PASS初始化完成。

INTLAPI.InitSDK(); // 初始化 sdk
Font font = null;  // 设置 LI PASS 界面的字体
LevelInfinite.InitLIP(font, Application.version, "en");

Unreal Engine

游戏启动的时候，应调用PNTSDK提供的初始化接口 INTLAPI.InitSDK 和 LevelInfinite.InitLIP 。

• 初始化过程会检查当前资源版本是否有可用的热更资源；
• 若有资源更新，将会自动下载新版资源，然后加载新版资源；
• 资源加载完成后，会触发 LI PASS 事件回调（LIEventObserver）中的 GN_READY 事件，此时LI PASS初始化完成。

#include "INTLSDKAPI.h" // Include the INTL header file

UINTLSDKAPI::Init();
FString Version = FApp::GetBuildVersion();
ULevelInfiniteAPI::InitLIP(GetGameInstance<UGameInstance>(), Version, TEXT("en"));

步骤四：设置 LI PASS 界面和邮件的语言

• 设置 LI PASS 界面使用的语言， 调用 SetLanguage 接口。
• 建议此处设置的语言与游戏语言保持一致；
• 设置好的语言类型也会作用于电子邮件中，比如 验证码邮件 等。

note

注意在切换游戏语言的时候，需要再次设置 SetLanguage 接口

Unity

接口详情：SetLanguage。

LevelInfinite.SetLanguage("en");

Unreal Engine

接口详情：SetLanguage。

ULevelInfiniteAPI::SetLanguage(TEXT("en"));

步骤五：设置UI根节点

在使用其他 LI PASS 功能之前，需调用 SetUIRoot 设置所有 LI PASS 界面的根节点，保证 UI 显示正确。

note

设置 UI 根节点后，请不要销毁该节点，否则 LI PASS UI 界面无法挂载，会产生预期外的行为。

LI PASS 界面的释放请通过界面按钮操作，不要强制销毁。在切换场景时若由 Unity 控制 GC（垃圾回收）可能会造成空指针错误出现。

Unity

接口详情： SetUIRoot。

LevelInfinite.SetUIRoot(uiRoot);

Unreal Engine

接口详情： SetUIRoot。

note

Unreal Engine,设置UI根节点时，需要将根节点铺满整个屏幕。

ULevelInfiniteAPI::SetUIRoot(uiRoot);

note

• 主机端的后续接入步骤，请参考 Console 账号方案步骤六。
• PC Standalone 登录方案的后续接入步骤，请参考 PC Standalone 账号方案步骤六。
• PC Store 登录方案的后续接入步骤，请参考 PC Store 账号方案步骤六。
• 移动端的后续接入步骤，请参考 移动端账号方案步骤六。

步骤六：打开 LI PASS 登录面板

这里以 移动端账号方案 为例，打开 LI PASS 界面。游戏业务需要根据自身需求，按照 Login 模块的对应账号方案指引接入。

Unity

LevelInfinite.OpenLoginPanel();

Unreal Engine

ULevelInfiniteAPI::OpenLoginPanel();

完成以上步骤，运行工程，正常情况下可以打开 LI PASS 的界面。

可能遇到的问题

Unity

1. Unity 导入时程序集问题

LI PASS 从 V1.08 版本开始支持程序集。如果项目不支持程序集，请执行以下步骤来移除：

1. 删除以下程序集定义文件。
2. 修改 luaSvr.cs，将程序集名从 LevelInfinite 换成 Assembly-CSharp。
3. 联系 Player Network 助手获取不带程序集的 AssetBundle 包。

2. [可选] 切换加载方式

LI PASS 默认的加载方式为 Editor 模式，用于在编辑器中正常跑通 LI PASS 流程。业务可选择在开发时，通过在菜单栏 LevelInfinite > AssetLoadMode 中选择对应的加载方式，将加载方式切换成 StreamingAssets 模式。

加载模式的选择不影响构建发布包的加载模式（默认 CDN）。

选项	说明
Editor	对应 INTL_DEBUG_LUA 宏，读取本地 Lua 文件
StreamingAssets	对应 INTL_USE_LOCAL_ASSETS 宏，加载 StreamingAssets 中的 AssetBundle
CDN	对应 Player Network 控制台 AssetBundle，如果控制台资源加载失败则加载 StreamingAssets 中的 AssetBundle

Unreal Engine

1. Cook 时的路径报错：LongPackageNameToFilename failed to convert ...

在 Cook 的时候如果报错 LongPackageNameToFilename failed to convert '/LevelInfinite'. Path does not map to any roots，需要修改 Cook 的路径 /LevelInfinite -> /LevelInfinite/，一般常出现在低于 UE4.27 版本。

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