Push 概念篇

UOS Push

UOS Push 是 Unity 资深团队打造的专业游戏内实时信息推送。通过这种功能，游戏系统能即时地向玩家发送相关的消息和通知，实现游戏中的各种实时聊天系统（包括世界聊天，团队聊天，群组聊天，在线私聊）。

这种推送信息可以包括各种类型，例如：

• 社交互动：如果游戏有社交元素，实时信息推送可能包括好友请求，私人消息，团队邀请等。
• 游戏事件：游戏可能会实时推送关于即将发生的活动，新的游戏内容，或者游戏更新的信息，服务器维护，错误报告，规则更改等。

Push SDK 主要由 3 个服务模块组成：消息服务、组队服务、玩家服务（需开通）。下文按“你会用到什么能力”的视角，分别介绍这三个服务模块的核心概念与边界。

消息服务

消息服务负责 Push 中最核心的“消息收发”能力，包括频道相关能力、频道消息、玩家消息（含离线消息）、玩家上下线通知、异地登录、玩家封禁等。

核心概念：

• 频道（Channel）：Push 中用于推送与收取信息的最小单位。
  • 公共频道：需预先在控制台或 API 配置，客户端 SDK 无法创建；常用于世界聊天、系统广播等。
  • 非公共频道：无需预先配置，可由客户端 SDK 创建并订阅；常用于队伍/小队、公会等“只对特定人群开放”的频道。
  • 订阅的生命周期：订阅是非持久化信息，玩家下线后已订阅频道会自动取消；再次上线需按需重新订阅。
• 频道消息：用于世界/公会/队伍聊天、系统广播等；订阅该频道的在线玩家会实时收到。频道消息支持缓存（缓存条数与有效期以实际开通配置为准），可参考 Q&A。
• 玩家消息（含离线消息）：用于玩家与玩家的一对一通信（如私聊、邀请、好友请求等）。默认只保证对在线玩家实时投递；开通离线玩家消息后，离线期间的消息会在上线后通过 onOfflinePlayerMessage 回调推送（限制见 Q&A：离线玩家消息功能限制）。
• 玩家上下线通知到频道：发送方配置“需要通知的频道列表”，当该玩家 Connect 成功 / 断线离线 / 自动重连成功 时会往这些频道推送状态通知；接收方订阅对应频道并在 onMessage 中通过 PlayerStatusAction 识别。
• 异地登录：同一账号在多个设备登录时，可通过初始化 SDK 时传入的异地登录回调进行处理（如提示并退出）。
• 玩家封禁：客户端收到封禁通知后会触发 onPlayerBanned 回调，可在回调里引导玩家退出游戏或重新登录。
• 消息存储（Message Storage）：用于本地存储与查看历史聊天记录（会话摘要、分页拉取、标记已读、删除等）。该功能由独立的消息存储 SDK 提供，详见 消息存储 SDK。

组队服务

组队服务是在 Push 实时连接能力之上构建的组队能力，提供创建/加入/离开队伍、锁定/解锁队伍、队伍可见性、邀请码、历史队友等功能。

主要能力：

• 自由组队：创建队伍或加入其他玩家队伍，并支持离开/解散等基础流程。
• 命名空间（Namespace）：用于隔离不同玩法/业务域的队伍；同一玩家在同一命名空间下只能存在于一个队伍中。
• 队伍管理：支持队伍人数上限、锁定/解锁、队伍可见性、邀请码等能力，便于实现“公开可加入/私密邀请”的多种组队模式。
• 队伍自定义属性（Properties）：可用键值对保存队伍的业务信息（如模式、地图、段位范围），用于展示或筛选。
• 队伍状态回调：用于监听成员变更、队伍状态变化、队伍属性更新等事件，方便客户端实时更新队伍 UI。
• 历史队友：用于查看过往队友信息，支持快速找回曾经的队友。

玩家服务

玩家服务指 Push 提供的玩家在线状态管理、属性管理以及根据条件随机在线玩家的功能（此服务需联系我们开通方可使用）。

主要能力：

• 玩家状态（Status）：在线（ONLINE）/繁忙（BUSY）/离线（OFFLINE）；可通过 SetPlayerStatus 设置 ONLINE 和 BUSY，OFFLINE 由连接状态决定。
• 玩家属性（Properties）：通过 SetPlayerProperties 设置当前玩家属性（如战力、等级等），用于后续筛选与匹配。
• 随机在线玩家：按属性条件随机获取一批在线玩家列表，常用于邀请组队、快速组队等流程。