콘텐츠로 이동

개인 매치 메이킹

개인 매치 메이킹은 한 명의 유저가 혼자 게임에 참여하고 싶은 경우 사용합니다.

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

Hive SDK로 개인 매치 메이킹 구현 시, 전체적인 동작 흐름은 아래의 도식도와 같습니다.

매칭 요청

사용자별로 매칭을 요청합니다.

요청 전에 matchId에 해당하는 매치 정보를 Hive 콘솔에 등록해야 합니다.

매칭 요청 시, 매치에 사용할 점수 point(0부터 10^10 미만 정수)와 매치에 사용할 부가 정보 extraData(닉네임, 레벨, 국가 등 256자 이내 정보)를 인자로 요청합니다.

Warning

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

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

API Reference: MatchMaking .requestMatchMaking

using hive;
        int matchId = 25;       // 콘솔에 등록한 matchId
        int point = 300;            // 매치 사용 점수 
        string extraData = "your extraData";    // 매치에 사용할 부가 정보
        MatchMaking.requestMatchMaking(matchId, point, extraData, (ResultAPI result, MatchMaking.MatchMakingData data) => {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMaking ::requestMatchMaking

#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::requestMatchMaking(matchId, point, extraData, [=](ResultAPI const & result, MatchMakingData data) {
                    if (result.isSuccess()) {
                            // call successful
                    } else {
                            // Call failed. See error code below
                    }
});

API Reference: MatchMaking.requestMatchMaking

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = 25            // 콘솔에 등록한 matchId
        val point = 300             // 매치 사용 점수
        val extraData = "your extraData";   // 매치에 사용할 부가 정보
        MatchMaking.requestMatchMaking(matchId, point, extraData, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking .requestMatchMaking

import com.hive.MatchMaking;
        import com.hive.ResultAPI;
        int matchId = 25;           // 콘솔에 등록한 matchId
        int point = 300;                // 매치 사용 점수
        String extraData = "your extraData";    // 매치에 사용할 부가 정보
        MatchMaking.INSTANCE.requestMatchMaking(matchId, 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 point: Int = 300                        // 매치 사용 점수
let extraData: String? = "your extraData"   // 매치에 사용할 부가 정보
MatchMakingInterface.requestMatchMaking(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
NSInteger point = 300;                      // 매치 사용 점수
NSString *extraData = @"your extraData";    // 매치에 사용할 부가 정보

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

requestMatchMatking(), getRequestingStatus() 메서드 호출의 결과로 MatchMakingData 객체를 전달합니다.

MatchMakingData 오브젝트의 구성

매칭 요청, 매칭 상태 확인 요청에 대한 응답으로 전달되는 오브젝트입니다. 요청 시 입력한 정보와 매칭 결과 정보를 포함합니다.

필드명 설명 타입
requestPlayerId 매치 요청한 사용자 playerId Long
requestGameIndex 매치 게임 인덱스 Int
requestMatchId 요청한 매치 아이디 (Hive 콘솔에 등록된 매치 형태) Int
requestStatus 매치 요청 상태 (requested: 매칭을 요청함, notRequested: 요청하지 않음(혹은, 이미 매칭되어 진행중인 매칭이 없음)) String
requestTimeUtc 매치 요청 시각 (ex : 2025-01-02T11:13:50.96) String
requestPoint 매치 점수 Int
requestExtraData 매치 요청시 전달한 기타 정보 (요청 시 extraData를 사용한 경우 존재) 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
matchingPlayerInfoList 매칭된 유저들의 정보 MatchingResultPlayerInfo 리스트 (matchingStatus가 matched인 경우, 개인 참가시 존재) Array
matchingTeamInfoList 매칭이 성사시 팀 정보 MatchingResultTeamInfo 리스트 (matchingStatus가 matched인 경우, 팀 참가시 존재) Array

MatchingResultTeamInfo 오브젝트의 구성

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

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

개인 매칭 요청 시 개인 매치, 팀 매치 모두 참가가 가능며, 매치 결과에 따라 위 오브젝트에 해당하는 matchingPlayerInfoList 혹은 matchingTeamInfoList가 전달됩니다.

MatchingResultPlayerInfo 데이터의 구성

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

필드명 설명 타입
playerId 매칭된 유저의 playerId Long
point 매칭된 유저의 point Int
extraData 매칭된 유저가 전달한 기타 정보 (해당 유저가 요청 시 extraData를 사용한 경우 존재) String


매칭 상태 확인

개인 매치에 참여한 유저의 매칭 상태를 확인합니다.

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

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

다음은 매칭 상태 확인 예제 코드입니다.

API Reference: MatchMaking .getRequestingStatus

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

API Reference: MatchMaking ::getRequestingStatus

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

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

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

API Reference: MatchMaking.getRequestingStatus

import com.hive.MatchMaking
        import com.hive.ResultAPI
        val matchId = 25            // 콘솔에 등록한 matchId
        MatchMaking.getRequestingStatus(matchId, object : MatchMaking.MatchMakingDataListener {
                    override fun onMatchMakingData(result: ResultAPI, data: MatchMaking.MatchMakingDataListener) {
                            if (result.isSuccess) {
                                    // call successful
                            } else {
                                    // Call failed. See error code below
                            }
                    }
})

API Reference: MatchMaking.INSTANCE .getRequestingStatus

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

API Reference: MatchMakingInterface.getRequestingStatus

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

API Reference: HIVEMatchMaking getRequestingStatus

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

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

매칭 진행 중

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

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

매칭 성사

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

시간 초과

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


매칭 삭제

기존 매칭을 삭제합니다.

아래의 경우 중 하나 이상에 해당할 때, 매칭을 삭제해야 합니다.

  • 사용자가 매칭을 취소했을 경우
  • 매칭 상태가 타임아웃인 경우 (matchingStatus : timeout)
  • 유저 간 게임이 정상적으로 완료된 경우

    ※ 게임 서버 또는 게임 클라이언트에 게임 결과(순위, 점수, 승패 여부 등) 데이터를 업데이트한 이후에 매칭 삭제를 요청해야함

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

API Reference: MatchMaking .deleteRequesting

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

API Reference: MatchMaking ::deleteRequesting

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

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

        MatchMaking::deleteRequesting(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.deleteRequesting(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.INSTANCE.deleteRequesting(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.deleteRequesting(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 deleteRequestingWithMatchId:matchId
                                       completion:^(HIVEResult *result, id data) {
    if ([result isSuccess]) {
        // call successful
    } else {
        // Call failed. See error code below
    }
}];

에러 코드

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