6labs >

适用于 Unity 的 6labs SDK

本节介绍如何将 6labs SDK 集成到您的 Unity 应用中。

前提条件

  • 需要 Unity 2021 LTS 或更高版本。旧版本可能可以运行，但不受积极支持。
  • 仅限 Apple 平台 — 请确保开发机器上已安装以下工具：
    • Xcode 26.2 或更高版本
    • CocoaPods 1.12.0 或更高版本
  • 您的 Unity 项目必须满足以下最低部署目标：
    • iOS — iOS 15 或更高版本
    • tvOS — tvOS 15 或更高版本
    • Android — API 级别 23（Android 6.0 Marshmallow）或更高版本

1. 下载并导入模块

6labs SDK 以 Unity 包文件的形式提供。

按照以下步骤将该模块添加到您的 Unity 项目中：

  1. 下载 6labs Unity SDK 最新版本 v3.9.0。
  2. 将安装包导入到您的 Unity 项目中：
    • 在 Unity 编辑器中点击 Assets > Import Package > Custom Package.
    • 从系统中选择已下载的 .unitypackage 文件。
    • 点击 Import 完成导入。

2. 开始观察游戏

使用 Start() 方法开始观察游戏，如下所示：

using SixLabs.SDK;

SixLabsSDK.Instance.Start( inGameId: "<optional_player_in_game_id>",
developerPayload: "<optional_developer_payload_here>",
callbackOnComplete: (sdkResponse, errorMessage) => {
// sdkResponse == SdkResponse.SUCCESS 表示 Start() 已成功完成
// 处理返回结果
// SixLabsSDK.Instance.CurrentState 可获取 SDK 当前的状态
} );

要求： SDK_STATE_IDLE。如果当前会话处于暂停状态，调用 Start() 将返回 ERROR_STATE_NOT_IDLE，请改用 Resume() 方法继续该暂停的会话。有关状态和响应代码的完整列表，请参阅SDK 状态和响应代码。

重要说明

  • 如果未传递 inGameId，观察到的会话可能会被丢弃，并且不会用于 AI 分析。缺少该字段时，无法将会话归属到玩家，而这是生成后续洞察所必需的。
  • 在开始观察游戏之前，请确保已获得用户同意。SDK不会自动请求权限，相关的授权流程需要在您的游戏逻辑中自行实现。
  • 作为推荐的最佳实践，您可以在游戏的EULA（最终用户许可协议）或隐私政策中说明游戏观察相关内容。
  • 请确保您的应用已为目标平台启用所需的网络访问权限。
  • 该SDK无法在Unity Editor中运行。要进行正确测试，您需要创建特定平台的构建并在真实设备上运行。在编辑器中，Start() 会改为使用 ERROR_NOT_SUPPORTED 调用 callbackOnComplete。

方法说明

以下为 Start() 方法的参考信息。

方法签名

public void Start(string inGameId = null, string developerPayload = null, Action<SdkResponse, string> callbackOnComplete = null)

参数说明

参数 类型 必填 说明
inGameId string 否 可选但推荐的用户标识符。如果省略，会话可能会被丢弃，且不会用于 AI 分析。
developerPayload string 否 与会话关联的可选开发者自定义元数据。该值会随会话请求原样转发，可用于附加自定义追踪信息或上下文信息。提供更丰富的 developerPayload 可以显著提升 AI 驱动的分析能力和会话理解效果。如需详细用例和 JSON 示例，请参阅开发者载荷示例页面。
示例：

  • 用户获取渠道
  • 活动 Campaign ID
  • 用户分群（例如：新用户 / 回访用户 / 付费用户）
  • A/B 测试变体（例如：variant_a、variant_b）— 将用户划分为不同的队列，并在 6labs 控制台中对比各队列的游戏数据。
  • 内部追踪标识
callbackOnComplete Action<SdkResponse, string> 否 调用完成后触发（无论成功或失败）。详见下方的回调说明。

回调

该回调是异步的，会返回 SdkResponse 和 errorMessage。errorMessage 在成功时为空，失败时说明具体原因。

响应值 说明
SUCCESS 会话已成功启动。
ERROR_STATE_NOT_IDLE SDK 未处于 SDK_STATE_IDLE 状态 — 可能已有会话在运行、会话已暂停，或前一个会话仍在停止中。
ERROR_NOT_SUPPORTED 当前平台完全不支持观察游戏 — 目前仅 Unity Editor 存在此情况。
ERROR_SESSION_FAILED 请求已被接受，但观察会话未能启动，SDK 已返回 SDK_STATE_IDLE。这可能是由于会话创建失败、设备性能限制、SDK 版本过旧、网络问题或其他初始化故障导致的。

注意

3. 设置游戏内 ID

使用 SetInGameId() 方法将玩家的游戏内 ID 与现有的观察会话关联。当 SDK 在用户账户创建之前完成初始化时，通常需要调用此方法，以便将已登录的用户与当前正在进行的会话关联起来。

SixLabsSDK.Instance.SetInGameId("<player_in_game_id>");

注意

  • 如果在 Start() 时已传入 inGameId，调用 SetInGameId() 将覆盖当前会话中已设置的值。

方法说明

以下为 SetInGameId() 方法的参考信息。

方法签名

public void SetInGameId(string inGameId)

参数说明

参数 类型 必填 说明
inGameId string 是 要与当前会话关联的玩家游戏内标识符。

4. 发送游戏事件

使用 SendGameEvent() 方法在活动的游戏观察会话期间记录自定义游戏事件。事件会被关联到该会话，并可用于在分析时对应到特定的游戏时刻。

bool result = SixLabsSDK.Instance.SendGameEvent( eventName: "<event_name>",
eventDataJson: "<event_data_as_json>" );

方法说明

以下为 SendGameEvent() 方法的参考信息。

方法签名

public bool SendGameEvent(string eventName, string eventDataJson)

参数说明

参数 类型 必填 说明
eventName string 是 要记录的自定义事件的名称。
eventDataJson string 是 包含该事件附加数据的 JSON 编码字符串。

返回值

值 说明
true 事件已被接受并加入上传队列。
false 事件被拒绝，例如 eventName 为空时。

5. 高级控制

Start() 会为新会话开始观察游戏。之后，您可以根据需要使用 Pause()、 Resume() 和 Stop() 方法来控制该会话。

5.1 暂停 (Pause)

调用 Pause() 方法暂停游戏观察。

SdkResponse result = SixLabsSDK.Instance.Pause();

要求： SDK_STATE_CAPTURING。有关状态和响应代码的完整列表，请参阅SDK 状态和响应代码。

重要说明

  • 该方法用于暂停游戏观察。
  • 之后可以再次调用 Resume() 恢复游戏观察。

方法说明

以下为 Pause() 方法的参考信息。

方法签名

public SdkResponse Pause()

返回值

值 说明
SUCCESS 该调用已被接受并执行。
ERROR_STATE_NOT_CAPTURING 当 SDK 未处于 SDK_STATE_CAPTURING 状态时返回 — 例如当前没有正在进行的游戏观察、会话已处于暂停状态，或已有一个停止操作正在进行。有关状态和响应代码的完整列表，请参阅SDK 状态和响应代码。

5.2 恢复 (Resume)

使用 Resume() 方法继续此前通过 Pause() 暂停的会话。

SixLabsSDK.Instance.Resume( callbackOnComplete: (sdkResponse, errorMessage) => {
// sdkResponse == SdkResponse.SUCCESS 表示 Resume() 已成功完成
// 处理返回结果
// SixLabsSDK.Instance.CurrentState 可获取 SDK 当前的状态
} );

要求： SDK_STATE_PAUSED。有关状态和响应代码的完整列表，请参阅SDK 状态和响应代码。

方法说明

以下为 Resume() 方法的参考信息。

方法签名

public void Resume(Action<SdkResponse, string> callbackOnComplete = null)

参数说明

参数 类型 必填 说明
callbackOnComplete Action<SdkResponse, string> 否 调用完成后触发（无论成功或失败）。详见下方的回调说明。

回调

该回调是异步的，会返回 SdkResponse 和 errorMessage。errorMessage 在成功时为空，失败时说明具体原因。

响应值 说明
SUCCESS 会话已成功恢复。
ERROR_STATE_NOT_PAUSED SDK 未处于 SDK_STATE_PAUSED 状态，因此没有可继续的暂停会话。
ERROR_SESSION_FAILED 请求已被接受，但暂停的会话未能恢复，SDK 已返回 SDK_STATE_IDLE。这可能是由于会话或运行时故障、网络问题，或其他导致会话无法恢复的故障。

注意

5.3 停止 (Stop)

使用 Stop() 方法永久结束当前会话。与 Pause() 不同，已停止的会话无法通过 Resume() 继续 — 如需开始新的会话，必须重新调用 Start()。

SixLabsSDK.Instance.Stop( callbackOnComplete: (sdkResponse, errorMessage) => {
// sdkResponse == SdkResponse.SUCCESS 表示 Stop() 已成功完成
// 处理返回结果
// SixLabsSDK.Instance.CurrentState 可获取 SDK 当前的状态
} );

要求： SDK_STATE_CAPTURING 或 SDK_STATE_PAUSED。有关状态和响应代码的完整列表，请参阅SDK 状态和响应代码。

方法说明

以下为 Stop() 方法的参考信息。

方法签名

public void Stop(Action<SdkResponse, string> callbackOnComplete = null)

参数说明

参数 类型 必填 说明
callbackOnComplete Action<SdkResponse, string> 否 调用完成后触发（无论成功或失败）。详见下方的回调说明。

回调

该回调是异步的，会返回 SdkResponse 和 errorMessage。errorMessage 在成功时为空，失败时说明具体原因。

响应值 说明
SUCCESS 调用已被接受，会话已结束。
ERROR_STATE_NOT_CAPTURING SDK 未处于 SDK_STATE_CAPTURING 或 SDK_STATE_PAUSED 状态，因此没有正在进行或已暂停的会话可以停止。

注意

6. SDK 状态和 响应代码

以下是 SDK 的状态及响应代码：

  • 您可以随时通过 SixLabsSDK.Instance.CurrentState 查看 SDK 当前的状态。
  • Start()、Pause()、Resume() 和 Stop() 只能在 SDK 处于有效状态时调用。在无效状态下调用会返回错误。
  • Pause() 会直接返回一个 SdkResponse。Start()、Resume() 和 Stop() 则通过可选的 callbackOnComplete 回调返回结果。
  • callbackOnComplete 回调是异步调用的。

6.1 状态

public enum SdkState {
SDK_STATE_IDLE = 100,
SDK_STATE_CAPTURING = 101,
SDK_STATE_STOPPING = 102,
SDK_STATE_PAUSED = 103
}
状态 值 说明
SDK_STATE_IDLE 100 SDK 未在观察游戏。这是默认状态，也是会话停止或启动失败后所返回的状态。
SDK_STATE_CAPTURING 101 SDK 正在主动观察游戏。这包括活动会话本身，以及缓冲和上传数据等后台处理工作。
SDK_STATE_STOPPING 102 会话正在停止。SDK 会先完成剩余的处理工作，再返回 SDK_STATE_IDLE。
SDK_STATE_PAUSED 103 会话已暂停。游戏观察暂时停止，但会话仍保持打开，此前已观察到的数据可以继续上传。

6.2 响应代码

public enum SdkResponse {
SUCCESS = 0,
ERROR_STATE_NOT_IDLE = 1000,
ERROR_STATE_NOT_CAPTURING = 1001,
ERROR_NOT_SUPPORTED = 1002,
ERROR_STATE_NOT_PAUSED = 1003,
ERROR_SESSION_FAILED = 1004
}
响应值 值 说明
SUCCESS 0 操作已被接受并成功完成。对于 Stop()，表示会话已结束。
ERROR_STATE_NOT_IDLE 1000 调用 Start() 时 SDK 未处于空闲状态。可能已有会话在运行、已暂停，或正在停止。
ERROR_STATE_NOT_CAPTURING 1001 调用 Pause() 或 Stop() 时 SDK 并未在观察游戏。Stop() 也可用于结束已暂停的会话。
ERROR_NOT_SUPPORTED 1002 在不支持观察游戏的平台上调用了 Start()，例如 Unity Editor。
ERROR_STATE_NOT_PAUSED 1003 调用 Resume() 时 SDK 并未处于暂停状态。当 SDK 处于空闲状态时，请使用 Start() 开始新的会话。
ERROR_SESSION_FAILED 1004 请求已被接受，但观察未能启动，SDK 已返回 SDK_STATE_IDLE。例如，会话创建可能因设备性能较低、SDK 版本过旧、网络问题或其他初始化问题而失败。该错误通过 callbackOnComplete 传递，而非以即时拒绝的形式返回。
×

目录

适用于 Unity 的 6labs SDK

目录

目录

适用于 Unity 的 6labs SDK
Text copied to clipboard
有疑问？请通过以下方式联系我们： dev-support@6labs.ai