跳至主要內容

Push SDK 初始化指南

Push SDK 初始化指南

1.安装配置 UOS Launcher

参考 Launcher 教程，安装 Launcher 后，关联 UOS APP， 开启 Push 服务并安装 Push SDK。

注意: 请务必确认在进行后续教程之前，已经成功完成了 Launcher 教程的安装步骤，否则可能导致后续接入无法顺利进行。

2.接入 Push

初始化SDK

参数介绍

  • onConnected: 连接完成后的回调方法，可通过回调参数ConnectResult来判断连接是否成功，其结构如下：
public class ConnectResult
{
    // 通过该参数判断是否成功连接到Push server
    public bool Success;
}
  • onMessage: 连接成功后，收到玩家或频道消息的回调方法，消息结构如下：(如不使用消息服务，可传空)
public class PushMessage
{
    // 消息发送方Id
    public string SenderId;
    // 消息发送方名字
    public string SenderName;
    // 收到channel消息时的channel名
    public string ChannelName;
    // 收到消息所属的消息类型，通过该字段可判断消息是频道消息还是玩家消息
    public MessageType MessageType;
    // 消息内容
    public byte[] Data;
}
  • onDisconnected: 断开连接的回调方法，断开的原因一般由客户端关闭连接，心跳检测超时，连接异常等情况，其结构如下：
public class DisconnectResult
{
    // 是否正常断开连接，当主动调用Disconnect方法时，该参数为true.
    public bool IsNormalClosed;
}
  • onSubscribe: 订阅频道的回调方法，可通过该方法查询频道是否订阅成功，订阅成功的频道可通过回调返回的SubscribeResult查看，其结构如下：(如不使用消息服务，可不传或者传空)
  • onRemoteLogin:异地登陆的回调方法，当一个账户发生异地多设备登陆时，老的设备会响应该方法，如你的游戏允许多设备登陆，可不传该参数
  • onOfflinePlayerMessage:离线消息的回调方法，当一个玩家离线期间其他玩家向他发送消息时，会进行缓存，玩家上线后将收到其离线期间收到的消息 (此功能需联系我们开通方可使用)
  • onReconnected:重连成功时的回调方法，连接期间可能存在断网等情况导致的断连，服务会进行自动重连，重连成功时，会响应该方法。当你使用玩家服务设置过玩家状态或者玩家属性时，掉线重连成功后需重新设置你的玩家属性，此时可在该回调方法里重新设置。
  • onPlayerBanned:玩家被封禁的回调方法，玩家被封禁时，该方法会响应，可在该方法里指引玩家退出游戏。

SDK鉴权

请您在使用 当前服务的SDK 之前，先确认是否需要同步启用我们的 UOS Passport 服务。
启用 UOS Passport 服务，可实现 UOS 系统账号体系打通（即多服务共用同一套 UOS Passport 账号，无需重复授权登录），简化账号管理流程。
特别注意 : UOS Passport 服务为独立计费服务，启用后将根据其专属计费规则额外计费： UOS Passport 计费规则

  • 不使用 UOS Passport。 请确保在调用 当前服务的SDK 提供的方法之前 已经完成用户授权:
using Unity.UOS.Auth;
// 用户授权 (每次初始化服务SDK 需进行用户授权)
string userId = <userId>; // 需要授权的 UserId
string userName = <userName>; // 可选, 需要授权的 UserName
await AuthTokenManager.GenerateAccessToken(userId, userName);

连接到 Push Server

// 连接到 push server，该方法是异步操作，连接成功后会响应初始化SDK传入的onConnected方法
try
{
     await PushSDK.Instance.ConnectAsync();
}
catch (PushSDKClientException ex)
{
     Debug.LogErrorFormat("Failed to connect server. clientEx {0}", ex);
}
catch (PushSDKServerException ex)
{
     Debug.LogErrorFormat("Failed to connect server. serverEx {0}", ex);
}
// 调用该方法后，通过初始化sdk实例传入的onConnected回调方法来判断连接结果

与 Push Server 断开连接

// 通常该方法可在 OnApplicationQuit event 调用
PushSDK.Instance.Disconnect();

销毁SDK实例

//使用实例
 PushSDK.Dispose();

3. SDK状态管理与断线重连

Push SDK instance 存在以下5种状态：

  • init (初始状态): Push SDK初始化成功后就是该状态。
  • connecting (正在连接中): 调用ConnectAsync方法开始连接，或断线后自动重连阶段，处于该状态。
  • connected (连接成功): 成功连上push server处于该状态。
  • connectFailure (连接失败): 因网络故障等原因无法连接到push server时会处于该状态。
  • disconnected (已断开连接): 客户端主动调用Disconnect方法或是断线重连失败后会处于该状态。

Push SDK instance 状态转换关系如下图：

Push 默认支持自动断线重连，当玩家因为网络波动，心跳超时等异常原因断开连接时，会自动尝试与服务端重新建立连接，但若因服务端崩溃等原因重连多次仍失败的情况下， 亦可在onDisconnected 回调方法中添加手动重连的逻辑，代码如下

private void OnDisconnect(DisconnectResult result)
{
    // 注意: 当玩家正常退出时，也就是 result.IsNormalClosed 为 true时，不可调用 PushSDK.Instance.ConnectAsync()方法，会陷入断线->重连->断线的循环
    if (!result.IsNormalClosed)
    {
        Debug.Log("Player abnormally disconnect, use Connect method to reconnect");
        // 该方法可重新找到一个正常工作的服务器供连接 (此处简写，实际需使用try catch 捕获ConnectAsync方法可能发生的异常)
        PushSDK.Instance.ConnectAsync("<playerId>");
    }
 }

此外，若玩家客户端断网持续比较久，比如超过30s甚至1分钟，则当玩家网络恢复时，push的自动重连功能可能已经结束，此时push sdk的状态可能已经是disconnected， 这种情况下，可自行监测网络恢复事件，在网络恢复时检测push sdk 状态，决定是否需要调用connect 方法来进行重连， 示例代码如下：

4.更多功能

如你仅需要异地登陆功能，这一篇文档涵盖的PushSDK 功能就可以满足需求了。但除此之外，PushSDK还包含三个服务模块

  • MessageService（ 消息服务）: 该模块支持频道的订阅，频道消息和玩家消息的发送，可以实现世界聊天，公会聊天和好友私聊等功能。
  • TeamsService（ 组队服务）: 该模块支持创建队伍或加入其他玩家的队伍，以及查看过往队友信息，快速找回曾经的队友等功能
  • PlayerService（ 玩家服务）: 该模块支持设置玩家在线状态和玩家属性，用于随机一组在线玩家用于邀请组队的功能 (此服务模块需联系我们开通方可使用)

5.附录

核心类&接口

异常类