團體配對

群組配對是在多個用戶希望作為同一隊伍一起參加遊戲時使用的。

群組匹配不僅可以在以群組為基礎的匹配請求時請求，還可以根據團隊成員的數量，當群組和個人組成團隊時請求。

Note

群組配對僅在群組配對中受支援，無法用於個人配對。

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

SDK中的配對操作流程¶

小組配對的進行順序如下。

創建群組（房間） → 成員群組參與 → 匹配請求

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

從小組領導者的角度看配對過程流程¶

從團體成員的角度看配對過程流程¶

創建群組¶

您必須先創建一個群組才能使用群組配對。

如果多個用戶想要一起參加遊戲，創建的組將被匹配為同一隊伍。

在呼叫群組創建方法時，對應於 matchId 的匹配信息必須在 Hive 控制台中預先註冊。

使用的參數為 matchId、分數 point（介於 0 到小於 10^10 的整數）以及額外資訊 extraData（包含 256 個字符內的資訊，如暱稱、等級、國家等）以用於比賽。

Note

用作參數的matchId的匹配單位必須設置為'team'。此外，創建該小組的用戶將是小組的領導者。

這裡是一個創建群組的示例代碼。

UnityC++KotlinJavaSwiftObjective-C

API 參考: MatchMaking .createGroup

using hive;

int matchId = 25;       // 在控制台中注册的 matchId
int point = 300;            // 用于比赛的积分
string extraData = "your extraData";    // 用于比赛的附加信息
MatchMaking.createGroup(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingGroupData data) => {
    if (result.isSuccess()) {
            // 调用成功
    } else {
            // 调用失败。请查看下面的错误代码
    }
});

API 參考: MatchMaking ::createGroup

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

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

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 Reference: HIVEMatchMaking createGroup

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

[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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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()) {
            // call successful
    } else {
            // Call failed. See error code below
    }
});

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 註冊在控制台

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

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            // The matchId registered in the console
MatchMakingInterface.leaveGroup(matchId: matchId) { result in
    if result.isSuccess() {
        // call successful
    } else {
        // Call failed. See error code below
    }
}

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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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 在控制台中注册

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

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) {
            // call successful
        } else {
            // Call failed. See error code below
        }
    }
})

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() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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"; // 群組代碼

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

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]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

成員資訊更新¶

群組中的成員可以更改他們的狀態或資訊。

在调用成员信息修改方法时，参数包括不包括组长的成员的准备状态 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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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() {
        // call successful
    }
    else {
        // Call failed. See error code below
    }
}

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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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 在控制台中注册

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

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()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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 呼叫因為參數不正確、網路問題，或在已處於配對請求狀態時發出配對請求而失敗