사전 준비

매치 메이킹 API를 사용하려면 다음 항목을 준비해야 합니다.

  • API 호출을 위한 인증 토큰(Hive Certification Key): Hive 콘솔 앱센터 > 프로젝트 관리 > 앱 검색 후 앱 선택 > 게임 상세 > 기본정보 > Hive 인증키
  • 게임 인덱스(gameIndex): Hive 콘솔 앱센터 > 프로젝트 관리 > 앱 검색 후 앱 선택 > 게임 상세 > 기본정보 > Game Index
  • 매치 ID(matchId): Hive 콘솔에서 매치 생성 시 확인하실 수 있습니다.

Request URL Root

서버 URL
LIVE api-match.withhive.com
SANDBOX sandbox-api-match.withhive.com

Common Response Codes

API 공통 응답코드입니다.

코드 값 설명
200 성공 각 API Response 참조
400 Bad Request 잘못된 Request Param 또는 Request Body 입력
401 Unauthorized 요청 메시지의 Authorization 헤더가 누락되었거나 그 값이 유효하지 않음
403 Forbidden API 호출을 위한 인증 토큰(Hive Certification Key)이 유효하지 않음
404 NotFound 잘못된 API Path 입력
500 Internal Server Error 서버 내부적으로 문제가 발생함

매치 요청

각 사용자가 매치를 요청할 때 호출합니다. matchId에 해당하는 매치를 Hive 콘솔에서 미리 생성해야 합니다.

Request URL

LIVE URL https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
SANDBOX URL https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP METHOD POST
CONTENT-TYPE application/json

Header Parameters

필드명 설명 타입 필수 여부
Authorization API 호출을 위한 인증 토큰 (Bearer) string Y

Path Parameters

필드명 설명 타입 필수 여부
gameIndex Hive 콘솔 앱센터에서 확인 가능한 프로젝트 식별자 int Y
matchId Hive 콘솔에서 생성한 각 매치 식별자 int Y

Request Body

필드명 설명 타입 필수 여부
playerId 계정 식별자 long Y
point 매치에 사용할 점수입니다. 입력 범위는 0 ~ 999,999,999입니다. 미입력 시 0으로 처리합니다. integer N
extraData 계정 부가 정보(닉네임, 레벨, 국가 등)입니다. 최대 256자까지 입력 가능합니다. 매치 결과에 같이 포함됩니다. string N

Response

필드명 설명
playerId 계정 식별자
matchInfo 요청 대상 정보

  • gameIndex: gameIndex 값
  • matchId: matchId 값
requstingStatus 요청 상태 정보

  • requested: 매치를 정상적으로 요청함
  • notRequested : 매치를 요청하지 않았거나, 매치가 이미 완료되어 현재 진행중인 매치가 없음
requestingInfo 요청 정보

  • requestTimeUtc: UTC+0 기준, 요청 시간
  • point: 요청 시 입력한 point
  • extraData : 요청 시 입력한 extraData
matchingInfo 매치 진행 정보(status)

  • matchingInProgress: 매치 진행중
  • timeout: 제한 시간 내에 매치가 이뤄지지 않음
  • matched: 매치 완료

Request Sample

Response Sample

매치 상태 확인

요청한 매치 상태를 확인합니다.

Request URL

LIVE URL https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
SANDBOX URL https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players
HTTP METHOD GET

Header Parameters

필드명 설명 타입 필수 여부
Authorization API 호출을 위한 인증 토큰 (Bearer) string Y

Path Parameters

필드명 설명 타입 필수 여부
gameIndex Hive 콘솔 앱센터에서 확인 가능한 프로젝트 식별자 int Y
matchId Hive 콘솔에서 생성한 각 매치 식별자 int Y

Query Parameters

필드명 설명 타입 필수 여부
id 사용자 ID(playerId) long Y

Response

필드명 설명
playerId 계정 식별자
matchInfo 요청 대상 정보

  • gameIndex: gameIndex 값
  • matchId: matchId 값
requstingStatus 요청 상태 정보

  • requested: 매치를 정상적으로 요청함
  • notRequested : 매치를 요청하지 않았거나, 매치가 이미 완료되어 현재 진행중인 매치가 없음
requestingInfo 요청 정보

  • requestTimeUtc: UTC+0 기준, 요청 시간
  • point: 요청 시 입력한 point
  • extraData : 요청 시 입력한 extraData
matchingInfo 매치 진행 정보(status)

  • matchingInProgress: 매치 진행중
  • timeout: 제한 시간 내에 매치가 이뤄지지 않음
  • matched: 매치 완료

Request Sample

Response Sample

개발사가 아직 매치 요청을 하지 않았을 때 매치 상태 결과는 아래와 같습니다.

 

매치 요청 후에 아직 매치가 진행중일 때에는 requested, matchingInProgress 결과를 반환합니다.

 

매치가 완료된 상태에서 요청 상태를 확인하면 matched 또는 timeout 결과를 반환합니다. 매치가 완료되었지만 매치 결과 콜백을 받기 전 상태입니다.

 

매치가 완료되면 Hive 서버는 개발사 서버로 매치 결과를 콜백으로 전달합니다. 개발사 서버가 매치 결과 콜백을 받고 응답으로 HTTPStatus 200을 Hive 서버에게 반환한 뒤, 매치 요청 상태를 다시 확인하면 아래와 같이 notRequested로 바뀌며 matchingInfo 키는 삭제됩니다. Hive 서버가 콜백 응답으로 HTTPStatus 200을 받으면, 개발사가 요청한 매치를 완료했다고 판단하고 매치 요청 트랜잭션을 삭제하기 떄문입니다.

 

매치 요청 전 매치 요청 후 매치 결과 생성 후 콜백 수신 후
requestingStatus notRequested requested requested notRequested
matchingInfo > Status N/A matchingInProgress matched or timeout N/A
비고 매치 진행 중 시점 콜백 수신 전 시점

매치 요청 취소

매치 요청을 취소합니다. 매치 요청을 취소하면 Hive 서버내에서 매치 요청 트랜잭션이 삭제됩니다.

매치 요청 후 매치가 완료되어 매치 결과 콜백을 받고 HTTPStatus 200을 응답으로 전송한 상태라면, Hive 서버 내부에서 매치가 완료된 것으로 보고 매치 요청 트랜잭션을 삭제합니다. 이 상태에서는 매치 요청 취소를 호출해도 이미 매치 요청 트랜잭션이 삭제된 상태이므로 요청 취소 작업은 실행되지 않으며 별도로 예외를 반환하지는 않습니다.

Request URL

LIVE URL https://api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
SANDBOX URL https://sandbox-api-match.withhive.com/gameindexes/{gameIndex}/matchmakings/{matchId}/players/{playerId}
HTTP METHOD DELETE

Header Parameters

필드명 설명 타입 필수 여부
Authorization API 호출을 위한 인증 토큰 (Bearer) string Y

Path Parameters

필드명 설명 타입 필수 여부
gameIndex Hive 콘솔 앱센터에서 확인 가능한 프로젝트 식별자 int Y
matchId Hive 콘솔에서 생성한 각 매치 식별자 int Y
playerId 사용자 ID long Y

Response

200 OK인 경우, Body는 비어있습니다.

Request Sample

Response Sample

정상 처리 시 특별한 응답 내용은 없습니다.

매치 결과 콜백

매치가 완료되면 Hive 서버에서는 개발사 서버로 매치 결과를 콜백으로 전달합니다. 매치 결과 콜백을 받은 개발사 서버는 HttpStatus 200을 응답으로 반환해야 합니다. Hive 콘솔에 원하는 서버 URL을 등록하면, 이 주소로 매치 결과를 콜백으로 전달합니다. 주소는 외부에서 접근 가능한 공개된 주소이어야 합니다. API 정보는 아래와 같습니다.

콜백 수신 URL (Hive 서버 → 개발사 서버)

Hive 콘솔에 개발사 서버 API 엔드포인트를 등록하면, Hive 서버는 매치가 완료될 때 이 엔드포인트로 콜백 결과를 전달합니다.

Header Parameters

필드명 설명 타입 필수 여부
X-Match-Signature HMAC SHA-256 알고리즘으로 Body 내용을 암호화한 Signature 값 string Y

콜백으로 전달하는 값

필드명 설명 타입
gameIndex 완료된 매치 gameIndex 값 int
matchId 완료된 매치 matchId 값 int
matchingInfos 매치 완료된 앱 사용자들 정보 배열, playerId 필드가 0인 사용자는 봇(Bot)으로 처리

  • matchingId: 매치 id
  • privateInfos: 개인전으로 매치된 사용자 정보 배열, timeoutPlayerInfos와 같은 형태
  • teamInfos: 팀전으로 매치된 사용자 정보 배열 (teamIndex: 팀 번호, playerInfos: 팀 구성원들 정보 배열로 timeoutPlayerInfos 같은 형태)
 json
timeoutPlayerInfos 매치되지 않고 Timeout된 앱 사용자들 정보 배열

  • extraData: 매치 요청 시 입력한 extraData
  • point: 매치 요청 시 입력한 point
  • playerId: 매치 요청 시 입력한 사용자 playerId
 json

콜백 전달 예시 (Hive 서버 → 개발사 서버)

 

콜백 결과 진위 여부는 Header Parameter X-Match-Signature 값으로 확인할 수 있으며, 알고리즘 계산에 사용할 키는 Hive 콘솔에서 확인할 수 있습니다. 아래는 Signature를 얻는 Java 코드 예시입니다.

 

Hive 서버에서 전달한 콜백을 정상 수신했다면 HttpStatus 200을 응답으로 반환해야 합니다.

  • HttpStatus 200으로 응답: 매치가 정상적으로 완료된 것으로 판단해 매치 요청을 취소합니다.
  • HttpStatus 200 외에 다른 값으로 응답 또는 Timeout: 일정 시간 간격으로 매치 결과 콜백을 다시 전달합니다.

지속적으로 HttpStatus 200 응답을 받지 못하면, 시스템 관리 차원에서 일정 시간동안 매치 결과를 전달하지 않습니다.