매치 메이킹¶

매치 메이킹은 온라인 게임에서 게임 사용자들이 같이 게임을 할 수 있도록 연결하는 프로세스로, 비슷한 수준을 가진 상대와 매칭시켜 균형 잡힌 게임 경험을 제공합니다.

시작하기¶

Hive에서 매치 메이킹을 사용하는 방식은 크게 2가지입니다.

Hive SDK
Hive Server API

여기서는 Hive SDK 방식을 안내합니다.

Hive SDK로 매치 메이킹을 사용하려면 먼저 다음 과정을 따라야 합니다.

매칭 방식과 매칭 인원에 대한 자세한 내용은 위 콘솔 가이드를 확인하세요.

매치 메이킹 SDK 전체 흐름¶

매치 메이킹 기능 구현 시 다음 흐름을 참고하세요.

매칭 요청¶

매칭을 요청합니다. 사용자별로 요청이 필요하며, matchId에 해당하는 매치 정보를 사전에 Hive 콘솔에 등록해야 합니다. 그리고 매치에 사용할 점수 point(0부터 10^10 미만 정수)와 매치에 사용할 부가 정보 extraData(닉네임, 레벨, 국가 등 256자 이내 정보)를 인자로 요청합니다.

Note

이미 매칭을 요청한 상태에서 매칭을 다시 요청 시, 기존 매칭이 중단되지는 않지만 에러 콜백(MatchMakingResponseError)을 전달합니다. 반드시 매칭 상태 확인으로 먼저 매칭 상태를 확인 후 매칭을 요청하세요.

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

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .requestMatchMaking

using hive;
        string 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;

        string 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;
        String 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 = "25"                  // 콘솔에 등록한 matchId
let point = 300                     // 매치 사용 점수
let extraData = "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"
NSString *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 오브젝트의 구성¶

필드명	설명	타입
matchPlayerId	요청한 사용자 playerId	Long
matchGameIndex	매치 게임 인덱스	Int
matchId	요청한 매치 아이디	Int
requestStatus	매치 요청 상태 (`requested`: 매칭을 요청함, `notRequested`: 요청하지 않음(혹은, 이미 매칭되어 진행중인 매칭이 없음))	String
requestTimeUtc	매치 요청 시각	String
requestPoint	매치 점수	Int
requestExtraData	매치 요청시 전달한 기타 정보	String
matchingStatus	매치 진행 상태 (`matchingInProgress`: 매칭 진행중, `timeout`: 제한 시간 내 매칭이 이루어 지지 않음, `matched`: 매칭이 성사됨)	String

매칭 상태 확인¶

사용자의 매칭 상태를 확인합니다. 매칭 상태로 다음 3개 중 1개를 반환합니다.

매칭 진행중
매칭 성사
시간 초과(Timeout)

매칭 진행중¶

상태가 매칭 진행중이면 반복해서 이 메서드를 호출하여 매칭 성사 상태가 되었는지 확인해야 합니다. 반복 호출 주기는 3~10초 간격으로 호출하는 것을 권장합니다. 앱의 구현 특성에 따라 시간 간격을 더 늘리는 것도 가능합니다.

매칭 성사¶

상태가 매칭 성사이면 개발사 게임을 실행합니다. 즉, Hive SDK가 게임을 같이할 사용자들을 서로 연결시켜주었으므로, 이 사용자들은 개발사 구현한 게임을 같이 즐기게 됩니다.

시간 초과¶

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

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

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .getRequestingStatus

using hive;
        string 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;

        string 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;
        String 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"
NSString *matchId = @"25";          // 콘솔에 등록한 matchId

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

매칭 삭제¶

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

사용자가 매칭을 취소했을 경우
매칭 상태가 타임아웃인 경우
정상적으로 사용자간 게임이 완료된 경우
- 게임 서버에서 게임 결과(순위, 점수, 승패 여부 등) 데이터를 업데이트한 이후에 매칭 삭제를 요청해야함

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

UnityC++KotlinJavaSwiftObjective-C

API Reference: MatchMaking .deleteRequesting

using hive;
        string 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;

        string 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;
        String 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"
NSString *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	Sign-In 이 되어 있지 않을 경우
RESPONSE_FAIL	MatchMakingResponseError	API 호출 시 잘못된 파라메터로 실패한 경우, 네트워크 문제로 실패한 경우, 이미 매칭 요청된 상태에서 매칭 요청한 경우