콘텐츠로 이동

매치 메이킹

매치 메이킹은 함께 게임을 할 수 있도록 게임 유저들을 연결해주는 기능으로, 비슷한 게임 실력을 가진 상대를 매칭시켜 균형 잡힌 게임 경험을 제공합니다.

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

  1. Hive SDK 적용하기
  2. Hive Server로 Matchmaking API 호출하기

본 가이드에서는 Hive SDK를 적용한 매치 메이킹 사용 방법을 설명합니다.


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

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

시작하기

Hive SDK로 매치 메이킹을 사용하려면 먼저 아래의 사항을 준비해야 합니다

  1. Hive 콘솔 앱센터에서 프로젝트 등록
  2. Hive 콘솔 매치 메이킹에서 매치 생성 매칭 방식과 매칭 인원에 관한 자세한 내용은 해당 콘솔 가이드에서 확인하세요.

매칭 요청

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

Note

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

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

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개를 반환합니다.

  1. 매칭 진행중
  2. 매칭 성사
  3. 시간 초과(Timeout)

매칭 진행중

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

매칭 성사

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

시간 초과

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


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

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

매칭 삭제

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

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

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

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 호출 시 잘못된 파라메터로 실패한 경우, 네트워크 문제로 실패한 경우, 이미 매칭 요청된 상태에서 매칭 요청한 경우