团体匹配

组队匹配用于多个用户希望作为同一团队一起参与游戏时。

组匹配不仅可以在按组基础进行匹配请求时请求，还可以根据团队成员的数量在组和个人形成团队时请求。

Note

组队匹配仅支持在组队匹配中使用，不能用于个人匹配。

本指南解释了用户如何通过输入创建组时提供的 GroupCode 值来加入组并请求匹配。

SDK中的 matchmaking 操作流程¶

小组匹配按以下顺序进行。

创建组（房间）→ 成员组参与 → 匹配请求

在使用 Hive SDK 实现组匹配时，匹配的整体流程取决于用户是组长还是组成员。

从组长的角度看配对过程流¶

从小组成员的角度看配对过程流程¶

创建组¶

您必须先创建一个组才能使用组匹配。

如果多个用户想要一起参加游戏，创建的组将被匹配为同一队伍。

在调用组创建方法时，必须在 Hive 控制台中预先注册与 matchId 相对应的匹配信息。

使用的参数是 matchId，得分 point（一个从 0 到小于 10^10 的整数），以及额外信息 extraData（256 个字符以内的信息，如昵称、等级、国家等），用于比赛。

Note

用于作为参数的matchId的匹配单位必须设置为'team'。此外，创建该组的用户将是组长。

这是创建组的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .createGroup

using hive;

int matchId = 25;       // matchId registered in the console
int point = 300;            // points used for the match
string extraData = "your extraData";    // additional information to be used for the match
MatchMaking.createGroup(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
            // call successful
    } else {
            // Call failed. See error code below
    }
});

API 参考: MatchMaking ::createGroup

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台注册的 matchId
int point = 300;                // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking::createGroup(matchId, point, extraData, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考: MatchMaking.createGroup

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台注册的 matchId
val point = 300             // 用于比赛的积分
val extraData = "your extraData";   // 用于比赛的附加信息

MatchMaking.createGroup(matchId, point, extraData, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .createGroup

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // matchId registered in the console
int point = 300;                // points used for the match
String extraData = "your extraData";    // additional information to be used for the match

MatchMaking.createGroup(matchId, point, extraData, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考: MatchMakingInterface.createGroup

import HIVEService
let matchId: Int = 25                       // matchId registered in the console
let point: Int = 300                        // points used for the match
let extraData: String? = "your extraData"   // additional information to be used for the match

MatchMakingInterface.createGroup(matchId: matchId, point: point, extraData: extraData) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 参考: HIVEMatchMaking createGroup

#import "HIVEService.h"
NSInteger matchId = 25;                 // 在控制台注册的 matchId
NSInteger point = 300;                      // 用于匹配的积分
NSString *extraData = @"your extraData";    // 用于匹配的附加信息

[MatchMakingInterface createGroupWithMatchId:matchId
                                              point:point
                                          extraData:extraData
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

加入小组¶

您可以加入小组。不是小组领导的用户可以加入小组以匹配为同一团队。

调用组参与方法时，使用的参数是 matchId，在创建组时发放的 GroupCode，用于匹配的分数 point（一个从 0 到小于 10^10 的整数），以及用于匹配的附加信息 extraData（昵称、等级、国家等信息，长度在 256 个字符以内）。

Note

不属于组长的用户必须请求加入该组。用于作为参数的matchId的匹配单位必须设置为'team'。

这是一个关于小组参与的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .joinGroup

using hive;

int matchId = 25;       // 在控制台注册的 matchId
string groupCode = "5001789"; // 组代码
int point = 300;            // 用于比赛的积分 
string extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.joinGroup(matchId, groupCode, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking ::joinGroup

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台注册的 matchId
string groupCode = "5001789";   // 组代码
int point = 300;                // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking::joinGroup(matchId, groupCode, point, extraData, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
            // 调用成功
    } else {
            // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking.joinGroup

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台注册的 matchId
val groupCode = "5001789"   // 组代码
val point = 300             // 用于比赛的积分
val extraData = "your extraData";   // 用于比赛的附加信息

MatchMaking.joinGroup(matchId, groupCode, point, extraData, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .joinGroup

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // 在控制台注册的 matchId
String groupCode = "5001789";   // 组代码
int point = 300;                // 用于比赛的积分
String extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.joinGroup(matchId, groupCode, point, extraData, (result, data) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMakingInterface.requestMatchMaking

import HIVEService
let matchId: Int = 25                       // 控制台中注册的 matchId
let groupCode: String = "5001789"           // 组代码
let point: Int = 300                        // 用于比赛的积分
let extraData: String? = "your extraData"   // 用于比赛的附加信息

MatchMakingInterface.joinGroup(matchId: matchId, point: point, extraData: extraData) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 参考: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSInteger matchId = 25;                 // matchId registered in the console
NSString *groupCode = @"5001789";           // group code
NSInteger point = 300;                      // points used for the match
NSString *extraData = @"your extraData";    // additional information to use for the match

[MatchMakingInterface joinGroupWithMatchId:matchId
                                          groupCode:groupCode
                                              point:point
                                          extraData:extraData
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

群体提款¶

我将离开这个小组。

如果任何一个组员处于“准备”状态，他们无法退出。此外，如果组长退出，剩下的成员中的一位将自动成为组长。如果没有剩余成员，组将被自动删除。

这是一个关于团体提款的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .leaveGroup

using hive;
int matchId = 25;       // The matchId registered in the console
MatchMaking.leaveGroup(matchId, (ResultAPI result) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考: MatchMaking ::leaveGroup

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // matchId registered in the console

MatchMaking::leaveGroup(matchId, [=](ResultAPI const & result) {
    if (result.isSuccess()) {
            // 调用成功
    } else {
            // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking.deleteRequesting

import com.hive.MatchMaking
import com.hive.ResultAPI
val matchId = 25            // 控制台中注册的 matchId
MatchMaking.leaveGroup(matchId, object : MatchMaking.MatchMakingResultListener {
    override fun onMatchMakingResult(result: ResultAPI) {
        if (result.isSuccess) {
            // 调用成功
        } else {
            // 调用失败。请参见下面的错误代码
        }
    }
})

API 参考: MatchMaking.INSTANCE .deleteRequesting

import com.hive.MatchMaking;
import com.hive.ResultAPI;
int matchId = 25;           // 控制台中注册的 matchId
MatchMaking.leaveGroup(matchId, (result) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMakingInterface.deleteRequesting

import HIVEService
let matchId = 25            // 控制台中注册的 matchId
MatchMakingInterface.leaveGroup(matchId: matchId) { result in
    if result.isSuccess() {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}

API 参考: HIVEMatchMaking deleteRequesting

#import "HIVEService.h"
NSInteger matchId = 25;          // 控制台中注册的 matchId

[MatchMakingInterface leaveGroupWithMatchId:matchId
                                       completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}];

群成员强制退出¶

组长可以强制移除特定成员。强制移除只能请求同一组的成员，并且在进行中的比赛中无法使用。

在调用组成员强制退出方法时，将要强制退出的成员的 targetPlayerId 作为参数使用。

以下是强制移除群组成员的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .kickGroupUser

using hive;

int matchId = 25;       // 在控制台注册的 matchId
long targetPlayerId = 123456789; // 被强制驱逐的成员的玩家 ID

MatchMaking.kickGroupUser(matchId, targetPlayerId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking ::kickGroupUser

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25; // matchId 注册在控制台
long long targetPlayerId = 123456789; // 强制驱逐的成员玩家 ID

MatchMaking::kickGroupUser(matchId, targetPlayerId, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
            // call successful
    } else {
            // Call failed. See error code below
    }
});

API 参考: MatchMaking.kickGroupUser

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25 // 在控制台注册的 matchId
val targetPlayerId = 123456789 // 强制导出的成员玩家 ID

MatchMaking.kickGroupUser(matchId, targetPlayerId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .kickGroupUser

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25; // 在控制台注册的 matchId
long targetPlayerId = 123456789; // 强制驱逐的成员玩家 ID

MatchMaking.kickGroupUser(matchId, targetPlayerId, (result, data) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考：MatchMakingInterface.kickGroupUser

import HIVEService
let matchId = 25                    // 控制台中注册的 matchId
let targetPlayerId = 123456789      // 要强制驱逐的成员玩家 ID

MatchMakingInterface.kickGroupUser(matchId: matchId, targetPlayerId) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 参考: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSInteger matchId = 25;                 // 控制台中注册的 matchId
NSNumber *targetPlayerId = 123456789;       // 要强制驱逐的成员的玩家 ID

[MatchMakingInterface kickGroupUserWithMatchId:matchId
                                          targetPlayerId:targetPlayerId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

基于用户的群组信息查询¶

根据组内用户查询组信息。它用于检查参与该组的其他用户的信息或在匹配请求后检查匹配结果。

建议定期检查群组用户的状态。

以下是一个根据组用户查询组信息的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .getGroupInfoByUser

using hive;

int matchId = 25;       // matchId registered in the console

MatchMaking.getGroupInfoByUser(matchId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking ::getGroupInfoByUser

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25; // matchId 在控制台中注册

MatchMaking::getGroupInfoByUser(matchId, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
            // call successful
    } else {
            // Call failed. See error code below
    }
});

API 参考: MatchMaking.getGroupInfoByUser

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25 // matchId 在控制台中注册

MatchMaking.getGroupInfoByUser(matchId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // 调用成功
        } else {
            // 调用失败。请参见下面的错误代码
        }
    }
})

API 参考: MatchMaking .getGroupInfoByUser

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25; // 在控制台中注册的 matchId

MatchMaking.getGroupInfoByUser(matchId, (result, data) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMakingInterface.getGroupInfoByUser

import HIVEService
let matchId = 25                    // 在控制台中注册的 matchId

MatchMakingInterface.getGroupInfoByUser(matchId: matchId) { result, data in
    if result.isSuccess() {
        // 调用成功
    }
    else {
        // 调用失败。请参阅下面的错误代码
    }
}

API 参考: HIVEMatchMaking getGroupInfoByUser

#import "HIVEService.h"
NSInteger matchId = 25;                 // 控制台中注册的 matchId

[MatchMakingInterface getGroupInfoByUserWithMatchId:matchId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

基于组代码的组信息查询¶

根据组代码查询组的信息。它用于检查组是否存在。

以下是一个根据组代码检索组信息的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .getGroupInfoByGroupCode

using hive;

string groupCode = "5001789";   // group code

MatchMaking.getGroupInfoByGroupCode(groupCode, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking ::getGroupInfoByGroupCode

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

string groupCode = "5001789"; // group code

MatchMaking::getGroupInfoByGroupCode(groupCode, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
            // call successful
    } else {
            // Call failed. See error code below
    }
});

API 参考: MatchMaking.getGroupInfoByGroupCode

import com.hive.MatchMaking
import com.hive.ResultAPI

val groupCode = "5001789" // group code

MatchMaking.getGroupInfoByGroupCode(groupCode, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .getGroupInfoByGroupCode

import com.hive.MatchMaking;
import com.hive.ResultAPI;

String groupCode = "5001789"; // Group code

MatchMaking.getGroupInfoByGroupCode(groupCode, (result, data) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参阅下面的错误代码
    }
});

API 参考: MatchMakingInterface.getGroupInfoByGroupCode

import HIVEService
let groupCode = "5001789" // Group code

MatchMakingInterface.getGroupInfoByGroupCode(groupCode: groupCode) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 参考: HIVEMatchMaking getGroupInfoByGroupCode

#import "HIVEService.h"
NSString *groupCode = @"5001789"; // 组代码

[MatchMakingInterface getGroupInfoByGroupCodeWithGroupCode:groupCode
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
}];

成员信息更新¶

群组中的成员可以更改他们的状态或信息。

在调用成员信息修改方法时，参数包括不包括组长的成员准备状态ready、用于比赛的分数point（一个从0到小于10^10的整数）以及用于比赛的附加信息extraData（如昵称、等级、国家等信息，最多256个字符）。

Warning

组内所有成员必须处于准备状态，组长才能发起匹配请求。
对于组长，准备值始终为真，改变为假将导致错误。

这是一个关于小组参与的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .updateGroupUser

using hive;

int matchId = 25;       // matchId registered in the console
bool ready = true;          // readiness status
int point = 300;            // points used for the match 
string extraData = "your extraData";    // additional information to be used for the match

MatchMaking.updateGroupUser(matchId, ready, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考: MatchMaking ::updateGroupUser

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台中注册的 matchId
bool ready = true;              // 准备状态
int point = 300;                // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking::updateGroupUser(matchId, ready, point, extraData, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
            // call successful
    } else {
            // Call failed. See error code below
    }
});

API 参考: MatchMaking.updateGroupUser

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台注册的 matchId
val ready = true            // 准备状态
val point = 300             // 用于比赛的积分
val extraData = "your extraData";   // 用于比赛的附加信息

MatchMaking.updateGroupUser(matchId, ready, point, extraData, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .updateGroupUser

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // matchId 注册在控制台
boolean ready = true;           // 准备状态
int point = 300;                // 用于比赛的积分
String extraData = "your extraData";    // 用于比赛的附加信息

MatchMaking.updateGroupUser(matchId, ready, point, extraData, (result, data) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMakingInterface.updateGroupUser

import HIVEService
let matchId: Int = 25                       // 控制台中注册的 matchId
let ready: Bool = true                      // 准备状态
let point: Int = 300                        // 比赛使用的积分
let extraData: String? = "your extraData"   // 用于比赛的附加信息

MatchMakingInterface.updateGroupUser(matchId: matchId, ready: ready, point: point, extraData: extraData) { result, data in
    if result.isSuccess() {
        // 调用成功
    }
    else {
        // 调用失败。请参见下面的错误代码
    }
}

API 参考: HIVEMatchMaking updateGroupUser

#import "HIVEService.h"
NSInteger matchId = 25;                 // matchId registered in the console
BOOL *ready = true;                         // group code
NSInteger point = 300;                      // points used for the match
NSString *extraData = @"your extraData";    // additional information to be used for the match

[MatchMakingInterface updateGroupUserWithMatchId:matchId
                                           ready:ready
                                           point:point
                                       extraData:extraData
                                      completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

匹配请求¶

请求匹配。一旦组内所有成员处于准备状态，组长可以发起匹配请求。

请求比赛时，前提条件如下。

请求时必须至少有 2 名组员。
不是组长（房间领导）的成员必须将其“准备好”状态设置为 true。
如果存在匹配项，必须在发出请求之前将其删除。
只有组长（房间领导）可以发出请求。

Warning

如果您在匹配请求已经进行时再次请求匹配，现有的匹配将不会被中断，回调函数将返回错误值（MatchMakingResponseError）。因此，请务必先通过检查匹配状态检查匹配状态，然后再请求匹配。

这是一个匹配请求的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .requestGroupMatching

using hive;
int matchId = 25;       // matchId registered in the console

MatchMaking.requestGroupMatching(matchId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking ::requestGroupMatching

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // 在控制台中注册的 matchId

MatchMaking::requestGroupMatching(matchId, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考: MatchMaking.requestGroupMatching

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台注册的 matchId

MatchMaking.requestGroupMatching(matchId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .requestGroupMatching

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // 在控制台中注册的 matchId

MatchMaking.requestGroupMatching(matchId, (result, data) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMakingInterface.requestGroupMatching

import HIVEService

let matchId = 25                    // 在控制台中注册的 matchId

MatchMakingInterface.requestGroupMatching(matchId: matchId) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 参考: HIVEMatchMaking requestGroupMatching

#import "HIVEService.h"

NSInteger matchId = 25;                 // 在控制台中注册的 matchId

[MatchMakingInterface requestGroupMatchingWithMatchId:matchId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

取消匹配请求（删除）¶

取消（删除）比赛。如果比赛满足以下一个或多个条件，则必须删除比赛。

如果用户取消比赛
如果比赛状态为超时
如果用户之间的游戏成功完成

您必须在更新游戏服务器上的比赛结果（排名、分数、胜负状态等）数据后请求删除比赛。

以下是取消（删除）匹配请求的示例代码。

UnityC++KotlinJavaSwiftObjective-C

API 参考: MatchMaking .deleteGroupMatching

using hive;
int matchId = 25;       // matchId registered in the console

MatchMaking.deleteGroupMatching(matchId, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API 参考: MatchMaking ::deleteGroupMatching

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

int matchId = 25;           // matchId registered in the console

MatchMaking::deleteGroupMatching(matchId, [=](ResultAPI const & result, MatchMakingGroupData data) {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMaking.deleteGroupMatching

import com.hive.MatchMaking
import com.hive.ResultAPI

val matchId = 25            // 在控制台注册的 matchId

MatchMaking.deleteGroupMatching(matchId, object : MatchMaking.MatchMakingGroupDataListener {
    override fun onMatchMakingGroupData(result: ResultAPI, data: MatchMaking.MatchMakingGroupDataListener) {
        if (result.isSuccess) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

API 参考: MatchMaking .deleteGroupMatching

import com.hive.MatchMaking;
import com.hive.ResultAPI;

int matchId = 25;           // 在控制台注册的 matchId

MatchMaking.deleteGroupMatching(matchId, (result, data) -> {
    if (result.isSuccess()) {
        // 调用成功
    } else {
        // 调用失败。请参见下面的错误代码
    }
});

API 参考: MatchMakingInterface.deleteGroupMatching

import HIVEService

let matchId = 25                    // 在控制台中注册的 matchId

MatchMakingInterface.deleteGroupMatching(matchId: matchId) { result, data in
    if result.isSuccess() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

API 参考: HIVEMatchMaking deleteGroupMatching

#import "HIVEService.h"

NSInteger matchId = 25;                 // 在控制台中注册的 matchId

[MatchMakingInterface deleteGroupMatchingWithMatchId:matchId
                                         completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

MatchMakingGroupData 对象结构¶

这是响应组匹配提供的主要功能请求时交付的对象。

创建群组
加入群组
强制移除群组成员
通过用户获取群组信息
通过群组代码获取群组信息
更新成员信息
请求匹配
取消（删除）匹配请求

响应对象包括请求期间输入的信息、组代码、组长信息、团队成员信息和匹配结果信息。

字段名称	描述	类型
groupCode	创建组时生成的组代码	字符串
ownerPlayerId	请求创建组的玩家ID（组长）	长整型
requestGameIndex	匹配游戏索引	整型
requestMatchId	请求的比赛ID（以在Hive控制台中注册的格式）	整型
requestStatus	比赛请求状态（`requested`：已请求比赛，`notRequested`：未请求（或没有进行中的比赛被匹配））	字符串
requestTimeUtc	比赛请求时间（例如：2025-01-02T11:13:50.96）	字符串
matchingStatus	匹配进度状态（`matchingInProgress`：匹配进行中，`timeout`：在时间限制内未发生匹配，`matched`：匹配成功）	字符串
matchingType	是否为团队参与或个人参与（如果matchingStatus为matched则存在）（`team`：团队，`player`：个人，`unknown`：如果没有匹配确认）	字符串
matchingId	分配给成功匹配的ID（如果matchingStatus为matched则存在）（例如：539:21_2025-01-02T11:45:55.25_1）	字符串
memberInfoList	当前属于该组的成员玩家信息列表 MatchMemberInfo	数组
matchingTeamInfoList	如果比赛成功的团队信息列表 MatchingResultTeamInfo（如果matchingStatus为matched则存在）	数组

MatchMemberInfo 对象结构¶

这是在参与团队比赛时传递的对象。它包含属于同一团队（组）的团队成员的用户信息。

字段名称	描述	类型
playerId	组成员的 playerId	Long
ready	组成员的准备状态	Boolean
point	组成员的积分	Int
extraData	组成员提供的其他信息（如果用户在请求时使用了 extraData，则存在）	String

MatchingResultTeamInfo 对象结构¶

这是在团队参与比赛并且匹配成功时（当 matchingStatus 为 matched 时）交付的对象。它包含团队索引和属于该团队的用户信息。

字段名称	描述	类型
teamIndex	团队的唯一索引	Int
playerInfos	属于团队的用户信息列表 MatchingResultPlayerInfo	Array

检查匹配状态¶

检查用户的匹配状态。

调用匹配状态检查方法时，它会返回以下三种匹配状态之一。

匹配进行中 (matchingStatus: matchingInProgress)
匹配成功 (matchingStatus: matched)
超时 (matchingStatus: timeout)

您可以使用通过用户获取组信息 API或通过组代码获取组信息 API检查匹配状态。

匹配进行中¶

如果匹配状态为进行中，您需要重复调用该方法以检查匹配状态，以查看它是否已达到匹配。

建议在3到10秒的间隔内调用重复调用周期。根据应用程序的实现特性，也可以进一步增加时间间隔。

匹配成功¶

如果匹配状态为匹配成功，开发者的游戏将被启动。这意味着通过Hive SDK 连接的用户处于可以一起玩游戏的状态，匹配的用户可以参与开发者的游戏。

超时¶

如果状态是超时（matchingStatus: timeout），您必须删除现有的匹配并请求重新匹配。

错误代码¶

错误代码	消息	描述
NEED_INITIALIZE	MatchMakingNotInitialized	如果未完成 SDK 设置 (AuthV4.setup)
INVALID_SESSION	MatchMakingNeedSignIn	如果未完成 AuthV4 登录
RESPONSE_FAIL	MatchMakingResponseError	如果由于参数不正确、网络问题，或者在已经处于匹配请求状态时发起匹配请求而导致 API 调用失败