Matchmaking API

사전 준비¶

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

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

Request URL root¶

Common response codes¶

API 공통 응답코드입니다.

매치 요청¶

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

Request URL¶

Header parameters¶

Path parameters¶

Request body¶

Response¶

Request sample¶

curl --location 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/request' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a' \
--data '{
   "playerId":100,
   "point": 1000
}'

Response sample¶

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

매치 상태 확인¶

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

Request URL¶

Header parameters¶

Path parameters¶

Query parameters¶

Response¶

Request sample¶

curl --location --request GET 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players?id=100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

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

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

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

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "requested",
   "requestingInfo": {
       "requestTimeUtc": "2024-06-05T05:09:28.72",
       "point": 1000
   },
   "matchingInfo": {
       "status": "matchingInProgress"
   }
}

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

    {
       "playerId": 100,
       "matchInfo": {
           "gameIndex": 1,
           "matchId": 1
       },
       "requestingStatus": "requested",
       "requestingInfo": {
           "requestTimeUtc": "2024-06-05T05:09:28.72",
           "point": 1000
       },
       "matchingInfo": {
           "status": "matched"
       }
   }

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

{
   "playerId": 100,
   "matchInfo": {
       "gameIndex": 1,
       "matchId": 1
   },
   "requestingStatus": "notRequested"
}

매치 요청 취소¶

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

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

Request URL¶

Header parameters¶

Path parameters¶

Response¶

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

Request sample¶

curl --location --request DELETE 'https://sandbox-api-match.withhive.com/gameindexes/1/matchmakings/1/players/100' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJIaXZlIiwiaWF0IjoxNzAyNDU4MTkzLCJqdGkiOiIxMzY2NDk4MjcxIn0.VSwvsTE-tS0sL_e9p9gNvHRkMCbsycSO4ObE4J2ya3a'

Response sample¶

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

매치 결과 콜백¶

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

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

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

Header parameters¶

콜백으로 전달하는 값¶

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

curl --location 'HIVE 콘솔에 등록한 앱 개발사 API 엔드포인트' --header 'Content-Type: application/json' --header 'X-Match-Signature: nj2YlgGTlLXcAhrl6ijSgfD71gTWokBiM8WPn72xxg8=' --data '{
   "gameIndex": 1,
   "matchId": 1,
   "matchingInfos": [
       {
           "matchingId": "1:1_2024-06-05T05:43:28.91_1",
           "privateInfos": [
               {
                   "playerId": 100,
                   "point": 1000
               },
               {
                   "playerId": 101,
                   "point": 1000
               }
           ]
       }
   ],
   "timeoutPlayerInfos": []
}'

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

import java.nio.charset.StandardCharsets;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
public class MatchSignature {  
   private static final String HMAC_SHA_256 = "HmacSHA256";
   private static final String UTF_8 = "UTF-8";
   public String getSignature(String secret, String httpRequestBody) throws Exception {
       SecretKeySpec key = new SecretKeySpec(secret.getBytes(), HMAC_SHA_256);
       Mac mac = Mac.getInstance(HMAC_SHA_256);
       mac.init(key);
       byte[] source = httpRequestBody.getBytes(UTF_8);

       return new String(Base64.getEncoder().encode(mac.doFinal(source)), StandardCharsets.UTF_8);
   }
}

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

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

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