Push & Passport 接入指南

本教程旨在使用 Push 来助力 Passport 服务实现玩家之间实时通知的功能

在使用 Passport 服务时. 有一些希望对方玩家能第一时间收到消息通知的。 如加好友，同意或是拒绝好友邀请，申请加入公会，通过加入公会申请等操作。 仅使用 Passport 服务的情况下是无法实现诸如此类的效果。

下面我们将以 Passport 好友模块为例，展示 Push 是如何实现实时通知功能的

第一步: 定义 FriendMessage Class

因 Push 发送玩家消息的单位是一个 byte 数组，所以我们定义一个 FriendMessage 类代表我们的消息内容，并在传输时序列化为 byte 数组

public class FriendMessage
{
    public FriendMessageType Type; // 消息类型
    public string PersonaId; //消息的来源
}

public enum FriendMessageType
{
    FriendRequest, //收到加好友请求
    AcceptFriendRequest, // 对方接受好友请求
    RejectFriendRequest, // 对方拒绝好友请求
    DeleteFriend, // 对方删除好友
}

我们还需要定义一个方法来发送好友消息

private void SendFriendMessage(string targetPlayerId, FriendMessage message)
{
    // targetPlayerId 即对方玩家在初始化PushSDK时传入的Id
    // 如果你的Push的PlayerId 使用的是 Passport personaId, 则此处传入目标玩家personaId
    // 如果你的Push的PlayerId 使用的是 Passport userId, 则此处传入目标玩家userId
    var bytes = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(message));
    PushSDK.Instance.MessageService.SendPlayerMessage(targetPlayerId, bytes);
}

第二步: 初始化 PushSDK 并连接到 Push server

初始化 PushSDK 时传入 OnMessage 回调需处理第一步定义的 FriendMessage

// 简易编写，实际需参考客户端SDK文档写法，使用try-catch捕捉InitializeAsync和ConnectAsync方法可能发生的异常
await PushSDK.InitializeAsync(OnConnect, OnMessage, OnDisconnect);
await PushSDK.Instance.ConnectAsync("<playerId>");

private void OnMessage(PushMessage message)
{
    var handleMessageCompleted = HandleFriendMessage(message);
    if (handleMessageCompleted)
    {
        Debug.Log("消息类型为好友类型，处理完成");
        return;
    }
    Debug.Log("收到其他类型消息");
    // 其他消息类型，可编写其他消息处理逻辑
}

private bool HandleFriendMessage(PushMessage message)
{
    try
    {
        var friendMessage = JsonConvert.DeserializeObject<FriendMessage>(Encoding.UTF8.GetString(message.Data));
        switch (friendMessage.Type)
        {
             case FriendMessageType.FriendRequest:
                  Debug.Log($"收到好友请求, 来自玩家 {friendMessage.PersonaId}");
                  break;
             case FriendMessageType.AcceptFriendRequest:
                  Debug.Log($"收到对方同意好友请求, 来自玩家 {friendMessage.PersonaId}");
                  break;
             case FriendMessageType.RejectFriendRequest:
                  Debug.Log($"收到对方拒绝好友请求, 来自玩家 {friendMessage.PersonaId}");
                  break;
             case FriendMessageType.DeleteFriend:
                  Debug.Log($"收到对方删除好友操作, 来自玩家 {friendMessage.PersonaId}");
                  break;
         }
         return true;
   }
   catch (JsonSerializationException e)
   {
        Debug.LogErrorFormat("反序列化失败, 该消息类型可能不是好友类型, {0}", e);
   }
   catch (Exception e)
   {
        Debug.LogErrorFormat("未知异常, {0}", e);
   }
   return false;
}

// 一个简易的OnConnect回调处理逻辑，实际可根据游戏场景需要自行改动
private void OnConnect(ConnectResult result)
{
     if (result.Success)
     {
          Debug.Log("connected successfully");
     }
     else
     {
         Debug.Log("connected failed");
     }
}

// 一个简易的OnDisconnect回调处理逻辑，实际可根据游戏场景需要自行改动
private void OnDisconnect(DisconnectResult result)
{
     if (!result.IsNormalClosed)
     {
         PushSDK.Instance.ConnectAsync();
     }
}

第三步: 在加好友，拒绝好友申请时使用 Push 实时发送消息到对方

以加好友举例, 消息发送成功之后，对方客户端会响应初始化 PushSDK 时传入的 onMessage 回调方法

var friendPersonaID = "<PersonaID>";
var ownPersonaID = "<PersonaID>";
// 使用Passport SDK 方法发送好友请求
await PassportFeatureSDK.Friends.SendFriendRequest(friendPersonaID);
var message = new FriendMessage()
{
     Type = FriendMessageType.FriendRequest,
     PersonaId = ownPersonaID,
};
// 使用第一步中定义的方法发送消息到对方(使用PersonaId作为Push的PlayerId)
SendFriendMessage(friendPersonaID, message);

至此，使用 Push 在 Passport 实现消息实时通知的完整链路就完成了，使用过程中，你可以自行拓展 FriendMessageType，比如增加拉黑好友，好友信息变更等，也可扩展 MessageType 到其它 Passport 服务功能，例如工会，邮件系统等， 只需要在 OnMessage 时候相应操作对应类型的消息即可。