本页尚未翻译,当前显示英文版本。
连接你的游戏
把 Unity 游戏连接到 PlayServ 只需要三样东西:SDK 包、一个 client key,以及一次 PlayServ.Connect() 调用。 client key 说明游戏属于哪个 Project 的哪个 Environment;其余的事情都由 SDK 完成,从让 Player 登录到保持连接。
开始之前
| 你需要 | 获取方式 |
|---|---|
| Unity 2021.3 或更高版本 | — |
| 一个 PlayServ Project | 创建 Project |
一个 client key(pk_…) | Projects → 你的 Project 的 API keys → Create key,类型选 Client。key 属于顶栏当前选中的 Environment。参见 API key 管理。 |
安装 SDK
SDK 是 com.playserv.sdk 包,可以从 OpenUPM 或其 Git 仓库安装。
添加 OpenUPM registry
在 Unity 中打开 Edit ▸ Project Settings ▸ Package Manager,添加一个 scoped registry:
| 字段 | 值 |
|---|---|
| Name | OpenUPM |
| URL | https://package.openupm.com |
| Scope(s) | com.playserv.sdk |
添加包
打开 Window ▸ Package Manager,选择 Add package by name,输入 com.playserv.sdk 和你需要的版本。请使用确切的版本号,确保每台机器、每个 build 都使用同一版 SDK。
如果改为从 Git 安装,选择 Add package from git URL,输入 https://github.com/playserv1/playserv-unity-sdk.git#<version>。
SDK 的可选扩展(例如使用 Apple、Google、Facebook、Epic 或 Steam 登录)以配套包的形式提供。在 Tools ▸ PlayServ ▸ Settings 的 SDK 模块设置中安装、移除和启用它们。
配置 SDK
打开 PlayServ 窗口
选择 Tools ▸ PlayServ ▸ Settings。配置位于 Control Room 下的 PlayServ Config 中。
选择平台
将 Environment 设为 Prod,即游戏要连接的 PlayServ 平台。
粘贴 client key
把你的 pk_… key 粘贴到 Client Token 中,并将 Game Version 设为你的 build 版本。
这里的 Environment 不是 Project 的 Environment
PlayServ 窗口中的 Environment 用于选择 PlayServ 平台:始终使用 Prod。Project 的 Environment(例如 dev 或 prod)由你粘贴的 client key 决定:请使用该 build 要访问的 Environment 的 key。
| 字段 | 说明 |
|---|---|
| Environment | PlayServ 平台。使用 Prod。 |
| Client Token | 你的 client key,会被打包进游戏。 |
| Server Token | 供编辑器工具(例如部署 Function)使用的 server key。它只留在编辑器中,绝不会进入 build。 |
| Game Version | 你的 build 版本,游戏连接时会发送。 |
key 保存在本地编辑器设置中,而不是 Project 文件里。CI 构建时,通过 PLAYSERV_CLIENT_TOKEN 环境变量传入 key,并设置 PLAYSERV_ENVIRONMENT=Prod。
首次连接
在第一个场景中添加类似这样的脚本:
using System;
using Playserv.Wrapper;
using UnityEngine;
public sealed class PlayServBootstrap : MonoBehaviour
{
async void Start()
{
try
{
bool online = await PlayServ.Connect();
Debug.Log(online ? $"Online as {PlayServAuth.PlayerId}" : "PlayServ connect failed");
}
catch (Exception e) // for example, a client key that isn't valid
{
Debug.LogError($"PlayServ sign-in failed: {e.Message}");
}
}
void OnDestroy() => PlayServ.Disconnect();
}
点击 Play。Console 中显示 Online as plr_…:游戏已连接,并以匿名 Player 身份登录。这个 Player 现在会出现在你的 key 所属 Environment 的 Players 中。
Connect() 做了什么、连接如何保持,参见 连接与 Session。
从旧版 SDK 升级
SDK 的 API 在各个版本之间有所变化。Tools ▸ PlayServ ▸ Migrate Project 会扫描你的脚本,找出旧的调用,展示改动,并应用你选中的改动;它会为修改的文件保留备份。
不再需要 Game ID 和 user ID
从 0.5 版本开始,client key 负责标识 Project 和 Environment,Player 来自其 Session。请手动从代码中删除 Game ID 或 user ID,Migrate Project 不会处理它们。PlayServ 窗口中的 Deployment Game Id 请留空:一旦设置,SDK 会把 Player 与未设置时保存的 Player 区分开。
无法连接时
| 现象 | 检查 |
|---|---|
Connect() 在登录时抛出异常 | client key:重新粘贴,并确认它没有被吊销。 |
Connect() 返回 false,错误为 00001 | 连接被拒绝:检查 client key、SDK 版本和 Game Version。 |
| 游戏能连接,但看不到你的数据 | key 所属的 Environment:它可能是其他 Environment 的 key。 |
| “Endpoint is required” | 通过代码配置时,设置 BackendServerAddress,参见 SDK 需要什么。 |
PlayServ.Ready 等旧调用无法编译 | 运行 Migrate Project。 |
后续步骤
- 连接与 Session —— 游戏连接和重连时会发生什么
- 用户登录 —— 让 Player 通过登录提供方登录
- 构建游戏 Schema —— 定义游戏要存储的数据
更新于 2026年10月19日