매칭 결과 콜백 API¶
매칭이 완료되면 Hive 서버에서는 개발사 서버로 콜백 API를 요청하여 매칭 결과를 전달하고 응답값을 받을 수 있습니다.
콜백 API 요청하여 매칭 결과를 전달하는 순서는 아래와 같습니다.
- Hive 콘솔에서 매치 연동 방식 을
서버 콜백
으로 선택 - Hive 콘솔에 콜백을 수신할 개발사 서버 URL 등록
- 매칭 완료 시, Hive 서버에서 개발사 서버로 콜백 API를 요청하여 매칭 결과를 전달
- 개발사 서버에서 매칭 결과를 정상으로 수신하면 Hive 서버로 HTTP 응답 상태 코드(
HttpStatus 200
) 반환
Request URL (개발사 서버 URL)¶
Hive 콘솔에 콜백 API를 요청하여 매칭 결과를 전달할 개발사 서버 URL을 API 엔드포인트로 등록합니다. 해당 URL은 외부에서 접근 가능한 공개된 주소여야 합니다.
Header parameters¶
콜백 API 요청 시, 헤더값은 아래와 같습니다.
필드명 | 설명 | 타입 | 필수 여부 |
---|---|---|---|
X-Match-Signature | HMAC SHA-256 알고리즘으로 전송 데이터를 암호화한 Signature 값 | string | Y |
Note
X-Match-Signature
값을 통해 매칭 결과 진위 여부를 판단할 수 있습니다.
X-Match-Signature
값은 아래의 예시 코드(Java)로 얻을 수 있으며, 코드에 사용되는 HMAC SHA-256 키 값은 Hive 콘솔에서 확인할 수 있습니다.
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);
}
}
Body parameters(콜백 API로 전달하는 매칭 결과)¶
콜백 API 요청 시, 전달되는 매칭 결과 데이터는 아래와 같습니다.
필드명 | 설명 | 타입 |
---|---|---|
gameIndex | 완료된 매칭의 gameIndex 값 | int |
matchId | 완료된 매칭의 matchId 값 | int |
matchingInfos | 매칭 완료된 앱 사용자들 정보 배열, `playerId` 필드가 `0`인 사용자는 봇(Bot)으로 처리
| json |
timeoutPlayerInfos | 매칭되지 않고 Timeout된 앱 사용자들 정보 배열
| json |
콜백 API 요청 예시 (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": []
}'
응답값 반환¶
콜백 API 요청에 의해 Hive 서버에서 전달하는 매칭 결과를 개발사 서버에서 정상 수신했다면 HttpStatus 200
을 응답으로 반환해야 합니다.
개발사 서버의 응답에 따라 Hive 서버에서 아래와 같은 방식으로 처리합니다.
HttpStatus 200
응답: 매칭 결과 전달을 정상적으로 완료된 것으로 판단하여 해당 콜백 API 요청을 종료합니다.HttpStatus 200
외에 다른 값으로 응답 또는 Timeout: 일정 시간 간격으로 다시 콜백 API를 요청하여 매칭 결과를 전달합니다.HttpStatus 200
응답이 없음 또는 다른 응답값이 없음: 지속적으로 응답이 없는 경우, 시스템 관리 차원에서 일정 시간 동안 매칭 결과를 전달하지 않습니다.