그룹 매치 메이킹

그룹 매치 메이킹은 여러 명의 유저가 같은 팀으로 함께 게임에 참여하고 싶은 경우 사용합니다.

그룹 매칭은 그룹 단위 매칭 요청 시 외에도, 팀 인원 수에 따라 그룹과 개인이 한 팀을 이루는 경우에도 요청할 수 있습니다.

Note

그룹 매치 메이킹은 그룹 매칭에서만 지원되며, 개인 매칭에서는 사용할 수 없습니다.

본 가이드에서는 유저가 그룹 생성 시 제공되는 GroupCode 값을 입력하여 그룹에 참여하여 매칭 요청하는 방법을 설명합니다.

SDK에서 매치 메이킹 동작 흐름¶

그룹 매치 메이킹은 크게 아래와 같은 순서로 진행됩니다.

그룹(방) 생성 → 멤버 그룹 참여 → 매칭 요청

Hive SDK로 그룹 매치 메이킹 구현 시, 매치 메이킹의 전체적인 동작 흐름은 유저가 그룹장인지 그룹 멤버인지에 따라 차이가 있습니다.

그룹장 입장에서 매치 메이킹 동작 흐름¶

그룹 멤버 입장에서 매치 메이킹 동작 흐름¶

그룹 생성¶

그룹 매치 메이킹을 사용하려면 먼저 그룹을 생성해야 합니다.

여러 명의 유저가 함께 게임에 참여하고 싶은 경우, 생성한 그룹이 같은 팀으로 매칭될 수 있도록 합니다.

그룹 생성 메소드 호출 시, matchId에 해당하는 매치 정보를 Hive 콘솔에 사전 등록해야 합니다.

전달 인자로 matchId, 매치에 사용할 점수 point(0부터 10^10 미만 정수), 그리고 매치에 사용할 부가 정보 extraData(닉네임, 레벨, 국가 등 256자 이내 정보)를 사용합니다.

Note

인자로 사용할 matchId의 매치 단위는 반드시 '팀'으로 설정되어야 합니다. 또한 그룹을 생성한 유저가 그룹장이 됩니다.

다음은 그룹 생성 예제 코드입니다.

UnityC++KotlinJavaSwiftObjective-C

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

API Reference: 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 Reference: 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 Reference: MatchMaking .createGroup

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

int matchId = 25;           // 콘솔에 등록한 matchId
int point = 300;                // 매치 사용 점수
String extraData = "your extraData";    // 매치에 사용할 부가 정보

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

API Reference: MatchMakingInterface.createGroup

import HIVEService
let matchId: Int = 25                       // 콘솔에 등록한 matchId
let point: Int = 300                        // 매치 사용 점수
let extraData: String? = "your extraData"   // 매치에 사용할 부가 정보

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
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의 매치 단위는 반드시 '팀'으로 설정되어야 합니다.

다음은 그룹 참여 예제 코드입니다.

UnityC++KotlinJavaSwiftObjective-C

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

API Reference: 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 Reference: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSInteger matchId = 25;                 // 콘솔에 등록한 matchId
NSString *groupCode = @"5001789";           // 그룹 코드
NSInteger point = 300;                      // 매치 사용 점수
NSString *extraData = @"your extraData";    // 매치에 사용할 부가 정보

[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
    }
}];

그룹 탈퇴¶

그룹에서 탈퇴합니다.

그룹 멤버 중 한명이라도 '준비 상태(Ready)'인 경우에는 탈퇴할 수 없습니다. 또한 그룹장이 탈퇴를 하면, 남은 멤버에서 한 명이 자동으로 그룹장이 됩니다. 남은 멤버가 없는 경우, 해당 그룹은 자동 삭제됩니다.

다음은 그룹 탈퇴 예제 코드입니다.

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .leaveGroup

using hive;
int matchId = 25;       // 콘솔에 등록한 matchId
MatchMaking.leaveGroup(matchId, (ResultAPI result) => {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

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

API Reference: MatchMaking.INSTANCE .deleteRequesting

import com.hive.MatchMaking;
import com.hive.ResultAPI;
int matchId = 25;           // 콘솔에 등록한 matchId
MatchMaking.leaveGroup(matchId, (result) -> {
    if (result.isSuccess()) {
        // call successful
    } else {
        // Call failed. See error code below
    }
});

API Reference: MatchMakingInterface.deleteRequesting

import HIVEService
let matchId = 25            // 콘솔에 등록한 matchId
MatchMakingInterface.leaveGroup(matchId: matchId) { result in
    if result.isSuccess() {
        // call successful
    } else {
        // Call failed. See error code below
    }
}

API Reference: HIVEMatchMaking deleteRequesting

#import "HIVEService.h"
NSInteger matchId = 25;          // 콘솔에 등록한 matchId

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

그룹 멤버 강제 퇴장¶

그룹장이 특정 멤버를 강제로 퇴장시킬 수 있습니다. 강제 퇴장은 같은 그룹 멤버에 한해서만 요청할 수 있으며 매칭 진행 중인 경우에는 사용할 수 없습니다.

그룹 멤버 강제 퇴장 메소드 호출 시, 전달 인자로 강제 퇴장시켜려는 멤버의 targetPlayerId를 사용합니다.

다음은 그룹 멤버 강제 퇴장 예제 코드입니다.

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .kickGroupUser

using hive;

int matchId = 25;       // 콘솔에 등록한 matchId
long targetPlayerId = 123456789; // 강제로 내보내려는 멤버 player id

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

API Reference: MatchMaking ::kickGroupUser

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

int matchId = 25; // 콘솔에 등록한 matchId
long long targetPlayerId = 123456789; // 강제로 내보내려는 멤버 player id

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

API Reference: MatchMaking.kickGroupUser

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

val matchId = 25 // 콘솔에 등록한 matchId
val targetPlayerId = 123456789 // 강제로 내보내려는 멤버 player 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 Reference: MatchMaking .kickGroupUser

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

int matchId = 25; // 콘솔에 등록한 matchId
long targetPlayerId = 123456789; // 강제로 내보내려는 멤버 player id

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

API Reference: MatchMakingInterface.kickGroupUser

import HIVEService
let matchId = 25                    // 콘솔에 등록한 matchId
let targetPlayerId = 123456789      // 강제로 내보내려는 멤버 player id

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

API Reference: HIVEMatchMaking requestMatchMaking

#import "HIVEService.h"
NSInteger matchId = 25;                 // 콘솔에 등록한 matchId
NSNumber *targetPlayerId = 123456789;       // 강제로 내보내려는 멤버 player 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 Reference: 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 Reference: 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 Reference: 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 Reference: MatchMaking .getGroupInfoByUser

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

int matchId = 25; // 콘솔에 등록한 matchId

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

API Reference: 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 Reference: 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 Reference: MatchMaking .getGroupInfoByGroupCode

using hive;

string groupCode = "5001789";   // 그룹 코드

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

API Reference: MatchMaking ::getGroupInfoByGroupCode

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

string groupCode = "5001789"; // 그룹 코드

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

API Reference: MatchMaking.getGroupInfoByGroupCode

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

val groupCode = "5001789" // 그룹 코드

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 Reference: 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 Reference: MatchMakingInterface.getGroupInfoByGroupCode

import HIVEService
let groupCode = "5001789" // 그룹 코드

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

API Reference: 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

그룹 내 모든 멤버가 준비 상태(ready)가 되어야 그룹장이 매칭 요청을 할 수 있습니다.
그룹장의 경우 ready 값은 항상 true 상태이며 false 상태로 변경 시 에러가 발생합니다.

다음은 그룹 참여 예제 코드입니다.

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .updateGroupUser

using hive;

int matchId = 25;       // 콘솔에 등록한 matchId
bool ready = true;          // 준비 상태
int point = 300;            // 매치 사용 점수 
string extraData = "your extraData";    // 매치에 사용할 부가 정보

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

API Reference: 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 Reference: 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 Reference: 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 Reference: 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 Reference: HIVEMatchMaking updateGroupUser

#import "HIVEService.h"
NSInteger matchId = 25;                 // 콘솔에 등록한 matchId
BOOL *ready = true;                         // 그룹 코드
NSInteger point = 300;                      // 매치 사용 점수
NSString *extraData = @"your extraData";    // 매치에 사용할 부가 정보

[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
    }
}];

매칭 요청¶

매칭을 요청합니다. 그룹 내 모든 멤버가 준비 상태(ready)가 되면, 그룹장은 매칭 요청을 할 수 있습니다.

매칭 요청 시, 사전 조건은 아래와 같습니다.

요청 시점에 그룹 멤버가 2명 이상 존재해야 합니다.
그룹장(방장)이 아닌 멤버는 '준비 상태'(Ready)가 true 상태여야 합니다.
기존에 진행한 매칭이 있을 경우, 삭제 후 요청해야 합니다.
그룹장(방장)만 요청할 수 있습니다.

Warning

이미 매칭을 요청한 상태에서 다시 매칭을 요청하면, 기존 매칭이 중단되지 않은 채 콜백 함수에서는 에러값(MatchMakingResponseError)을 반환합니다. 따라서 반드시 매칭 상태 확인으로 먼저 매칭 상태를 확인 후 매칭을 요청하세요.

다음은 매칭 요청 예제 코드입니다.

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .requestGroupMatching

using hive;
int matchId = 25;       // 콘솔에 등록한 matchId

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

API Reference: 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 Reference: 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 Reference: 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 Reference: 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 Reference: 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 Reference: MatchMaking .deleteGroupMatching

using hive;
int matchId = 25;       // 콘솔에 등록한 matchId

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

API Reference: 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 Reference: 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 Reference: 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 Reference: 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 Reference: 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	그룹 생성 요청시 생성된 그룹 코드	String
ownerPlayerId	그룹 생성을 요청한 playerId(그룹장)	Long
requestGameIndex	매치 게임 인덱스	Int
requestMatchId	요청한 매치 아이디 (Hive 콘솔에 등록된 매치 형태)	Int
requestStatus	매치 요청 상태 (`requested`: 매칭을 요청함, `notRequested`: 요청하지 않음(혹은, 이미 매칭되어 진행중인 매칭이 없음))	String
requestTimeUtc	매치 요청 시각 (ex : 2025-01-02T11:13:50.96)	String
matchingStatus	매치 진행 상태 (`matchingInProgress`: 매칭 진행중, `timeout`: 제한 시간 내 매칭이 이루어 지지 않음, `matched`: 매칭이 성사됨)	String
matchingType	팀 참가 또는 개인 참가 여부 (matchingStatus가 matched인 경우 존재) (`team`: 팀, `player`: 개인, `unknown`: 매칭 확인이 되지 않은 경우)	String
matchingId	성사된 매칭에 부여된 id (matchingStatus가 matched인 경우 존재) (ex : 539:21_2025-01-02T11:45:55.25_1)	String
memberInfoList	현재 그룹에 속한 멤버 플레이어 정보 MatchMemberInfo 리스트	Array
matchingTeamInfoList	매칭이 성사시 팀 정보 MatchingResultTeamInfo 리스트 (matchingStatus가 matched인 경우 존재)	Array

MatchMemberInfo 오브젝트의 구성¶

팀 매치에 참여한 경우 전달되는 오브젝트입니다. 같은 팀(그룹)에 속한 팀 멤버의 유저 정보가 포함되어 있습니다.

필드명	설명	타입
playerId	그룹 멤버 playerId	Long
ready	그룹 멤버의 준비 상태	Boolean
point	그룹 멤버의 point	Int
extraData	그룹 멤버가 전달한 기타 정보 (해당 유저가 요청 시 extraData를 사용한 경우 존재)	String

MatchingResultTeamInfo 오브젝트의 구성¶

팀 매치에 참가하고 매칭이 성사되었을 때(matchingStatus가 matched인 경우) 전달되는 오브젝트입니다. 팀 인덱스와 팀에 속한 유저의 정보가 포함되어 있습니다.

필드명	설명	타입
teamIndex	팀 고유 인덱스	Int
playerInfos	팀에 속한 유저들의 정보 MatchingResultPlayerInfo 리스트	Array

매칭 상태 확인¶

사용자의 매칭 상태를 확인합니다.

매칭 상태 확인 메소드 호출 시, 아래의 3가지 매칭 상태 중 1가지를 반환합니다.

매칭 진행 중 (matchingStatus : matchingInProgress)
매칭 성사 (matchingStatus : matched)
시간 초과 (matchingStatus : timeout)

매칭 상태 확인은 그룹 유저를 기준으로 그룹 정보 조회 또는 그룹 코드를 기준으로 그룹 정보 조회 API 를 사용하여 확인할 수 있습니다.

매칭 진행 중¶

매칭 상태가 매칭 진행중이면 해당 매칭 상태 확인 메서드를 반복해서 호출하여 매칭 성사 상태가 되었는지 확인해야 합니다.

반복 호출 주기는 3~10초 간격으로 호출하는 것을 권장합니다. 앱의 구현 특성에 따라 시간 간격을 더 늘리는 것도 가능합니다.

매칭 성사¶

매칭 상태가 매칭 성사이면 개발사 게임을 실행합니다. 즉, Hive SDK를 통해 게임을 함께 할 유저들이 연결된 상태로, 매칭된 유저들은 개발사 게임에 참여할 수 있습니다.

시간 초과¶

상태가 타임아웃(matchingStatus: timeout)이면 기존 매칭을 삭제하고 매칭을 다시 요청해야 합니다.

에러 코드¶

Error Code	Message	Description
NEED_INITIALIZE	MatchMakingNotInitialized	SDK Setup이 되어 있지 않은 경우 (AuthV4.setup)
INVALID_SESSION	MatchMakingNeedSignIn	AuthV4 Sign-In이 되어 있지 않은 경우
RESPONSE_FAIL	MatchMakingResponseError	API 호출 시 잘못된 파라메터로 실패한 경우, 네트워크 문제로 실패한 경우, 이미 매칭 요청된 상태에서 매칭 요청한 경우