Pre-requisites
To use the matchmaking API, you need to prepare the following items.
- Authentication token for API calls (
Hive Certification Key): Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information > Hive Certification Key - Game index (
gameIndex): Hive Console App Center > Manage Project > Select your game from the game list > Game Details > Basic Information > Game Index - Match ID (
matchId): You can check this when creating a match in the Hive console.
Request URL root
| Server | URL |
|---|---|
| LIVE | api-match.withhive.com |
| SANDBOX | sandbox-api-match.withhive.com |
Common response codes
These are the common API response codes.
| Code | Value | Description |
|---|---|---|
| 200 | Success | Refer to each API response |
| 400 | Bad Request | Incorrect request parameters or request body input |
| 401 | Unauthorized | The authorization header in the request message is missing or invalid |
| 403 | Forbidden | The authentication token (Hive Certification Key) for the API call is invalid |
| 404 | Not Found | Incorrect API path |
| 500 | Internal Server Error | An internal server error occurred |
Request Match
Call this API when each user requests a match. The match corresponding to matchId must be pre-created in the Hive console.
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
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | Authentication token for API calls (Bearer) | string | Y |
Path Parameters
| Field Name | Description | Type | Required |
|---|---|---|---|
| gameIndex | Project identifier available in the Hive console App Center | int | Y |
| matchId | Each match identifier created in the Hive console | int | Y |
Request Body
| Field Name | Description | Type | Required |
|---|---|---|---|
| playerId | Account identifier | long | Y |
| point | Score to be used for the match. The input range is 0 ~ 999,999,999. If not entered, 0 will be used. |
integer | N |
| extraData | Additional account information (nickname, level, country, etc.). Up to 256 characters can be entered. It is included in the match result. | string | N |
Response
| Field Name | Description |
|---|---|
| playerId | Account identifier |
| matchInfo | Request target information
|
| requestingStatus | Request status information
|
| requestingInfo | Request information
|
| matchingInfo | Match status information (status)
|
Request Sample
|
1 2 3 4 5 6 7 8 9 |
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
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "playerId": 100, "matchInfo": { "gameIndex": 1, "matchId": 1 }, "requestingStatus": "requested", "requestingInfo": { "requestTimeUtc": "2024-06-05T05:09:28.72", "point": 1000 }, "matchingInfo": { "status": "matchingInProgress" } } |
Check Match Status
Check the status of the requested match.
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
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | Authentication token for API call (Bearer) | string | Y |
Path Parameters
| Field Name | Description | Type | Required |
|---|---|---|---|
| gameIndex | Project identifier available in Hive Console App Center | int | Y |
| matchId | Identifier for each match generated in the Hive Console | int | Y |
Query Parameters
| Field Name | Description | Type | Required |
|---|---|---|---|
| id | User ID (playerId) |
long | Y |
Response
| Field Name | Description |
|---|---|
| playerId | Account identifier |
| matchInfo | Requested information
|
| requestingStatus | Request status information
|
| requestingInfo | Request information
|
| matchingInfo | Match status information (status)
|
Request Sample
|
1 2 3 4 |
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
The match status when you have not yet made a match request is as follows.
|
1 2 3 4 5 6 7 8 9 10 |
{ "playerId": 100, "matchInfo": { "gameIndex": 1, "matchId": 1 }, "requestingStatus": "notRequested" } |
Request Match returns requested and matchingInProgress statuses when the match is still in progress.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "playerId": 100, "matchInfo": { "gameIndex": 1, "matchId": 1 }, "requestingStatus": "requested", "requestingInfo": { "requestTimeUtc": "2024-06-05T05:09:28.72", "point": 1000 }, "matchingInfo": { "status": "matchingInProgress" } } |
When checking the request status after the match is completed, it returns matched or timeout results. This is the state where the match is completed but the match result callback has not yet been received.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
{ "playerId": 100, "matchInfo": { "gameIndex": 1, "matchId": 1 }, "requestingStatus": "requested", "requestingInfo": { "requestTimeUtc": "2024-06-05T05:09:28.72", "point": 1000 }, "matchingInfo": { "status": "matched" } } |
Once the match is completed, the Hive server sends the match result callback to your server. If your server receives the match result callback, returns HTTPStatus 200 to the Hive server, and if you check the match request status again, it will change to notRequested and the matchingInfo key will be deleted as shown below. This is because the Hive server considers your match request is completed upon receiving HTTPStatus 200 in response to the callback and deletes the match request transaction.
|
1 2 3 4 5 6 7 8 9 10 |
{ "playerId": 100, "matchInfo": { "gameIndex": 1, "matchId": 1 }, "requestingStatus": "notRequested" } |
| Before Match Request | After Match Request | After Match Result Created | After Callback Reception | |
|---|---|---|---|---|
| requestingStatus | notRequested | requested | requested | notRequested |
| matchingInfo > Status | N/A | matchingInProgress | matched or timeout | N/A |
| Remarks | match in progress | before callback reception |
Cancel Match Request
Cancel the match request. When you cancel the match request, the match request transaction will be deleted from the Hive server.
If the match is completed after Request Match and you have received the Match Result Callback and responded with HTTPStatus 200, the Hive server will consider the match completed and delete the match request transaction. In this state, even if you call to cancel the match request, as the match request transaction has already been deleted, the cancellation operation will not be executed and no exception will be returned.
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
| Field Name | Description | Type | Required |
|---|---|---|---|
| Authorization | Authentication token for API call (Bearer) | string | Y |
Path parameters
| Field Name | Description | Type | Required |
|---|---|---|---|
| gameIndex | Project identifier available in the Hive Console App Center | int | Y |
| matchId | Identifier for each match created in the Hive Console | int | Y |
| playerId | User ID | long | Y |
Response
If it is 200 OK, the body is empty.
Request Sample
|
1 2 3 4 |
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
There is no specific response if the request is canceled normally.
Match Result Callback
When a match is completed, the Hive server sends the match result to the your server as a callback. If your server received the match result callback without any issue, your server should respond with HttpStatus 200. By registering the desired server URL in the Hive console, the match result will be sent to this address as a callback. The address must be a publicly accessible URL. The API information is as follows.
Callback reception URL (Hive server → Your server)
When your server API endpoint is registered in the Hive console, the Hive server sends the callback result to this endpoint when the match is completed.
Header parameters
| Field Name | Description | Type | Required |
|---|---|---|---|
| X-Match-Signature | The signature value of the encrypted body contents with the HMAC SHA-256 algorithm | string | Y |
Values passed with the callback
| Field Name | Description | Type |
|---|---|---|
| gameIndex | The gameIndex value of the completed match | int |
| matchId | The matchId value of the completed match | int |
| matchingInfos | An array of information of the app users who are matched. Users with a playerId field value of 0 are considered bots.
|
json |
| timeoutPlayerInfos | An array of information of app users who were not matched and timed out
|
json |
Callback example (Hive server → Your server)
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
curl --location 'The API endpoint of your server registered in the Hive Console.' --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": [] }' |
You can verify the authenticity of the callback result using the value of the Header Parameter X-Match-Signature, and the key to be used for the algorithm calculation can be found in the Hive console. Below is an example of Java code to obtain the Signature.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
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); } } |
If the callback sent from the Hive server is successfully received, you should return an HTTP status 200 as a response.
- Response with HttpStatus 200: It is considered that the match has been successfully completed, so the match request will be canceled.
- Response with a value other than HttpStatus 200 or Timeout: The match result callback will be resent at regular intervals.
If the Hive server can’t receive HTTP status 200 response continuously, the match result call back will not be delivered for a certain period for system management purposes.