跳到主要内容
快速开始

本页尚未翻译,当前显示英文版本。

连接你的游戏

把 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:

字段值
NameOpenUPM
URLhttps://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。

字段说明
EnvironmentPlayServ 平台。使用 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。

后续步骤

更新于 2026年10月19日