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

  • gameIndex: gameIndex value
  • matchId: matchId value
requestingStatus Request status information

  • requested: Match requested successfully
  • notRequested: Match was not requested, or the match is already completed so there is no ongoing request for match
requestingInfo Request information

  • requestTimeUtc: Request time in UTC+0
  • point: point entered at the time of request
  • extraData: extraData entered at the time of request
matchingInfo Match status information (status)

  • matchingInProgress: Match in progress
  • timeout: Match did not made within the time limit
  • matched: Match completed

Request Sample

Response Sample

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

  • gameIndex: gameIndex value
  • matchId: matchId value
requestingStatus Request status information

  • requested: Match requested successfully
  • notRequested: Match was not requested, or the match is already completed so there is no ongoing request for match
requestingInfo Request information

  • requestTimeUtc: Request time in UTC+0
  • point: point entered at the time of request
  • extraData: extraData entered at the time of request
matchingInfo Match status information (status)

  • matchingInProgress: Match in progress
  • timeout: Match not completed within the time limit
  • matched: Match completed

Request Sample

Response sample

The match status when you have not yet made a match request is as follows.

 

Request Match returns requested and matchingInProgress statuses when the match is still in progress.

 

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.

 

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.

 

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

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.

  • matchingId: The match id
  • privateInfos: An array of information of users matched in a solo game (the same format as timeoutPlayerInfos)
  • teamInfos: An array of information of users matched in a team game (teamIndex: team number, playerInfos: An array of team members’ information, the same format as timeoutPlayerInfos)
 json
timeoutPlayerInfos An array of information of app users who were not matched and timed out

  • extraData: The extraData entered when the match was requested
  • point: The point entered when the match was requested
  • playerId: The playerId entered when the match was requested
 json

Callback example (Hive server → Your server)

 

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.

 

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.