组队服务 SDK 接入指南

1. 初始化Push SDK并连接到 Push Server

参考 Push SDK 初始化指南，初始化 Push SDK并连接到 Push Server。

2.集成示例

创建队伍

try
{
    string teamName = "teamName";
    uint maxPlayer = 5;
    // 玩家在一个命名空间下只能存在在一个队伍中，如果不传则为默认命名空间default
    string teamNamespace = "namespace1";
    Team res = await PushSDK.Instance.TeamService.CreateTeamAsync(teamName, maxPlayer, teamNamespace);
    // 创建的队伍的唯一Id
    Debug.Log(res.TeamId);
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to create team. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to create team. server ex: {0}", ex);
    throw;
}

public class Team
{
    /// <summary>
    /// 队伍Id
    /// </summary>
    public string TeamId;
    /// <summary>
    /// 队伍命名空间
    /// </summary>
    public string Namespace;
    /// <summary>
    /// 队伍名称
    /// </summary>
    public string Name;
    /// <summary>
    /// 队长
    /// </summary>
    public string Owner;
    /// <summary>
    /// 队伍内玩家列表
    /// </summary>
    public List<string> Players;
    /// <summary>
    /// 队伍最大人数
    /// </summary>
    public uint MaxPlayerCount;
    /// <summary>
    /// 队伍创建时间
    /// </summary>
    public Timestamp CreatedAt;
    /// <summary>
    /// 队伍上次锁定时间
    /// </summary>
    public Timestamp LastLockedAt;
    /// <summary>
    /// 队伍是否被锁定
    /// </summary>
    public bool Locked;
    /// <summary>
    /// 队伍可见性
    /// </summary>
    public TeamVisibility visibility;
    /// <summary>
    /// 队伍邀请码
    /// </summary>
    public string TeamCode;
}

/// <summary>
/// 队伍可见性
/// </summary>
public enum TeamVisibility
{
    /// <summary>
    /// 公开
    /// </summary>
    PUBLIC,
    /// <summary>
    /// 私密，PickTeams时不会获取到
    /// </summary>
    PRIVATE
}

获取当前组队信息

try
{
    List<Team> res = await PushSDK.Instance.TeamService.GetPlayerTeamsAsync();
    // 当前所在的队伍数量
    Debug.Log(res.Count);
    foreach (var team in res)
    {
        Debug.Log(team.TeamId);
        Debug.Log(team.Name);
        foreach (var playerId in team.Players)
        {
            Debug.Log(playerId);
        }
    }
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to get teams. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to get teams. server ex: {0}", ex);
    throw;
}

加入队伍

try
{
    // 队伍唯一Id
    var teamId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    Team res = await PushSDK.Instance.TeamService.JoinTeamAsync(teamId);
    Debug.Log(res.Name);
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to join team. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to join team. server ex: {0}", ex);
    throw;
}

离开队伍

try
{
    // 队伍唯一Id
    var teamId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    await PushSDK.Instance.TeamService.LeaveTeamAsync(teamId);
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to leave team. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to leave team. server ex: {0}", ex);
    throw;
}

离开所有队伍

try
{
    await PushSDK.Instance.TeamService.LeaveAllTeamsAsync();
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to leave all teams. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to leave all teams. server ex: {0}", ex);
    throw;
}

锁定组队

try
{
    // 队伍唯一Id
    var teamId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    await PushSDK.Instance.TeamService.LockTeamAsync(teamId);
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to lock team. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to lock team. server ex: {0}", ex);
    throw;
}

解散组队，只有owner有权限解散组队

// 只有owner有权限解散组队
try
{
    // 队伍唯一Id
    var teamId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    await PushSDK.Instance.TeamService.DismissTeamAsync(teamId);
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to dismiss team. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to dismiss team. server ex: {0}", ex);
    throw;
}

获取组过队的队友列表

try
{
    // 队伍唯一Id
    List<Teammate> res = await PushSDK.Instance.TeamService.ListHistoricalTeammatesAsync();
    Debug.Log(res.Count);
    foreach (var teammate in res)
    {
        Debug.Log(teammate.PlayerId);
        Debug.Log(teammate.Status);
    }
}
catch(PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to list historical teammates. client ex: {0}", ex);
    throw;
}
catch(PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to list historical teammates. server ex: {0}", ex);
    throw;
}

public class Teammate
{
    /// <summary>
    /// 玩家Id
    /// </summary>
    public string PlayerId;
    /// <summary>
    /// 上次组队时间
    /// </summary>
    public Timestamp LastCollabTime;
    /// <summary>
    /// 玩家状态
    /// </summary>
    public PlayerStatus Status;
}

踢出队伍内玩家

// 只有队伍owner有权限踢出队内玩家
try
{
    // 队伍唯一Id
    var teamId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";
    // 需要踢出的玩家Id
    var playerId = "xxxxxxxxx";
    await PushSDK.Instance.TeamService.KickPlayer(teamId, playerId);
}
catch (PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to kick player. client ex: {0}", ex);
    throw;
}
catch (PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to kick player. server ex: {0}", ex);
    throw;
}

根据邀请码获取队伍信息

try
{
    // 队伍邀请码
    var teamCode = "xxxxxx";
    var team = await PushSDK.Instance.TeamService.GetTeamByCode(teamCode);
    // 可以通过获取到的team信息中的Id去调用JoinTeam，加入朋友的队伍
    Debug.Log(team.TeamId);
}
catch (PushSDKClientException ex)
{
    Debug.LogErrorFormat("Failed to get team by code. client ex: {0}", ex);
    throw;
}
catch (PushSDKServerException ex)
{
    Debug.LogErrorFormat("Failed to get team by code. server ex: {0}", ex);
    throw;
}

4. 附录

基础服务核心类&接口

/// <summary>
/// 创建队伍
/// </summary>
/// <param name="name">队伍名称</param>
/// <param name="maxPlayerCount">队伍人数限制</param>
/// <param name="teamNamespace">命名空间，选填，不填默认为default</param>
/// <param name="visibility">队伍可见性，默认为PUBLIC</param>
/// <param name="generateTeamCode">是否生成队伍邀请码</param>
/// <returns>队伍信息</returns>
public Task<Team> CreateTeamAsync(string name, uint maxPlayerCount, string teamNamespace = null, TeamVisibility? visibility = null, bool? generateTeamCode = null);

/// <summary>
/// 获取当前组队信息
/// </summary>
/// <param name="teamNamespace">命名空间，选填，⽤于指定获取玩家在某个特定命名空间下的组队信息，不填则获取所有</param>
/// <returns>队伍列表</returns>
public Task<List<Team>> GetPlayerTeamsAsync(string teamNamespace = null);

/// <summary>
/// 加入队伍
/// </summary>
/// <param name="teamId">队伍Id</param>
/// <returns>队伍信息</returns>
public Task<Team> JoinTeamAsync(string teamId);

/// <summary>
/// 离开队伍
/// </summary>
/// <param name="teamId">队伍Id</param>
public Task LeaveTeamAsync(string teamId);

/// <summary>
/// 离开所有队伍
/// </summary>
/// <param name="namespaceList">命名空间，选填</param>
public Task LeaveAllTeamsAsync(List<string> namespaceList = null);

/// <summary>
/// 锁定组队
/// </summary>
/// <param name="teamId">队伍Id</param>
public Task LockTeamAsync(string teamId);

/// <summary>
/// 解散组队，只有owner有权限解散组队
/// </summary>
/// <param name="teamId">队伍Id</param>
public Task DismissTeamAsync(string teamId);

/// <summary>
/// 获取组过队的队友列表
/// </summary>
/// <param name="count">数量</param>
/// <param name="filterOfflinePlayers">是否只返回在线的玩家</param>
/// <returns>组过队的队友列表</returns>
public Task<List<Teammate>> ListHistoricalTeammatesAsync(uint? count = null, bool? filterOfflinePlayers = null);

/// <summary>
/// 踢出队伍内玩家，只有owner有权限
/// </summary>
/// <param name="teamId">队伍Id</param>
/// <param name="kickedPlayerId">需要踢出的玩家Id</param>
/// <returns></returns>
public Task KickPlayer(string teamId, string kickedPlayerId);

/// <summary>
/// 根据邀请码获取队伍信息
/// </summary>
/// <param name="teamCode">队伍邀请码</param>
/// <returns></returns>
public Task<Team> GetTeamByCode(string teamCode);