Client Matchmaking API Reference

The matchmaking service matches some players into one battle based on a specific ruleset. The key processes include searching for players and battle placement on a dedicated server. It supports solo and multiple players' matchmaking.

API List

API	Description
GetCurrentMatchmakings	Get current activate matchmaking tickets of the player.
StartMatchmaking	Start a matchmaking request. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.
StartMatchmaking_V2	Start a matchmaking request. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.
StartP2PMatchmaking	Start a P2P matchmaking request. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.
CancelMatchmaking	Cancel a matchmaking request
DescribeMatchmaking	Get detail process info of a matchmaking request
JoinMatchmaking	Accept to join a multiplayer matchmaking request when the matchmaking status is "Preparing"
RejectMatchmaking	Reject a multiplayer matchmaking request when the matchmaking status is "Preparing"
AcceptMatchedBattle	Accept the matched battle when matchmaking_status turn to Accepting. This interface should be called within accepting_timeout after matchmaking_status turn to Accepting, otherwise it will be considered a refusal
RejectMatchedBattle	Reject the matched battle when matchmaking_status turn to Accepting
GetConcurrentMatchmakingPlayerCount	Reject the matched battle when matchmaking_status turn to Accepting

Event List

Event	Description
SetOnMatchmakingProcessChanged	The event will be triggered when the matchmaking process changed.

API Details

GetCurrentMatchmakings

Get current activate matchmaking tickets of the player.

/**
 * Get current activate matchmaking tickets of the player.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetCurrentMatchmakings(
    PgosDataCallback<CurrentMatchmakingsInfo> result_callback);

Parameters:

Param	Type	Description
result_callback	PgosDataCallback<CurrentMatchmakingsInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

StartMatchmaking

Start a matchmaking request. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.

/**
 * Start a matchmaking request.
 * Tips: In order to enhance the reliability of the service event reception, after calling this API, 
 *       the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. 
 *       This ensures that the service continues to function even when the persistent connection is disconnected.
 * 
 * @param configuration_name Name of matchmaking configuration
 * @param player_info_list Players who start matchmaking together, and they must be set to the same team.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void StartMatchmaking(
    const pgos::pstring& configuration_name,
    const pgos::pvector<MatchmakingPlayerInfo>& player_info_list,
    PgosDataCallback<StartMatchmakingInfo> result_callback);

Parameters:

Param	Type	Description
configuration_name	const std::string&	Name of matchmaking configuration
player_info_list	const std::vector<MatchmakingPlayerInfo>&	Players who start matchmaking together, and they must be set to the same team.
result_callback	PgosDataCallback<StartMatchmakingInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

StartMatchmaking_V2

/**
 * Start a matchmaking request.
 * Tips: In order to enhance the reliability of the service event reception, after calling this API, 
 *       the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. 
 *       This ensures that the service continues to function even when the persistent connection is disconnected.
 * 
 * @param params 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void StartMatchmaking_V2(
    const StartMatchmakingParams& params,
    PgosDataCallback<StartMatchmakingInfo> result_callback);

Parameters:

Param	Type	Description
params	const StartMatchmakingParams&
result_callback	PgosDataCallback<StartMatchmakingInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

StartP2PMatchmaking

Start a P2P matchmaking request. Tips: In order to enhance the reliability of the service event reception, after calling this API, the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. This ensures that the service continues to function even when the persistent connection is disconnected.

/**
 * Start a P2P matchmaking request.
 * Tips: In order to enhance the reliability of the service event reception, after calling this API, 
 *       the SDK will automatically invoke relevant APIs to poll the event status from the backend within a certain time period. 
 *       This ensures that the service continues to function even when the persistent connection is disconnected.
 * 
 * @param params 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void StartP2PMatchmaking(
    const StartMatchmakingParams& params,
    PgosDataCallback<StartMatchmakingInfo> result_callback);

Parameters:

Param	Type	Description
params	const StartMatchmakingParams&
result_callback	PgosDataCallback<StartMatchmakingInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

CancelMatchmaking

Cancel a matchmaking request

/**
 * Cancel a matchmaking request
 * 
 * @param ticket_id Ticket id for the matchmaking request
 * @param reason The reason for the cancel action, not necessary
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void CancelMatchmaking(
    const pgos::pstring& ticket_id,
    const pgos::pstring& reason,
    PgosDataCallback<CancelMatchmakingInfo> result_callback);

Parameters:

Param	Type	Description
ticket_id	const std::string&	Ticket id for the matchmaking request
reason	const std::string&	The reason for the cancel action, not necessary
result_callback	PgosDataCallback<CancelMatchmakingInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

DescribeMatchmaking

Get detail process info of a matchmaking request

/**
 * Get detail process info of a matchmaking request
 * 
 * @param ticket_id Ticket id for the matchmaking request
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void DescribeMatchmaking(
    const pgos::pstring& ticket_id,
    PgosDataCallback<MatchmakingProcessInfo> result_callback);

Parameters:

Param	Type	Description
ticket_id	const std::string&	Ticket id for the matchmaking request
result_callback	PgosDataCallback<MatchmakingProcessInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

JoinMatchmaking

Accept to join a multiplayer matchmaking request when the matchmaking status is "Preparing"

/**
 * Accept to join a multiplayer matchmaking request when the matchmaking status is "Preparing"
 * 
 * @param ticket_id Ticket id for the matchmaking request
 * @param player_info Player's detail info
 * @param reason The reason for the join action, not necessary
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void JoinMatchmaking(
    const pgos::pstring& ticket_id,
    const MatchmakingPlayerInfo& player_info,
    const pgos::pstring& reason,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
ticket_id	const std::string&	Ticket id for the matchmaking request
player_info	const MatchmakingPlayerInfo&	Player's detail info
reason	const std::string&	The reason for the join action, not necessary
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

RejectMatchmaking

Reject a multiplayer matchmaking request when the matchmaking status is "Preparing"

/**
 * Reject a multiplayer matchmaking request when the matchmaking status is "Preparing"
 * 
 * @param ticket_id Ticket id for the matchmaking request
 * @param reason The reason for the reject action, not necessary
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void RejectMatchmaking(
    const pgos::pstring& ticket_id,
    const pgos::pstring& reason,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
ticket_id	const std::string&	Ticket id for the matchmaking request
reason	const std::string&	The reason for the reject action, not necessary
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

AcceptMatchedBattle

Accept the matched battle when matchmaking_status turn to Accepting. This interface should be called within accepting_timeout after matchmaking_status turn to Accepting, otherwise it will be considered a refusal

/**
 * Accept the matched battle when matchmaking_status turn to Accepting. This interface should be called
 *  within accepting_timeout after matchmaking_status turn to Accepting, otherwise it will be considered a refusal
 * 
 * @param ticket_id Ticket id for the matchmaking request
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void AcceptMatchedBattle(
    const pgos::pstring& ticket_id,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
ticket_id	const std::string&	Ticket id for the matchmaking request
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

RejectMatchedBattle

Reject the matched battle when matchmaking_status turn to Accepting

/**
 * Reject the matched battle when matchmaking_status turn to Accepting
 * 
 * @param ticket_id Ticket id for the matchmaking request
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void RejectMatchedBattle(
    const pgos::pstring& ticket_id,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
ticket_id	const std::string&	Ticket id for the matchmaking request
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

GetConcurrentMatchmakingPlayerCount

Reject the matched battle when matchmaking_status turn to Accepting

/**
 * Reject the matched battle when matchmaking_status turn to Accepting
 * 
 * @param params Matchmaking configuration name
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void GetConcurrentMatchmakingPlayerCount(
    const GetConcurrentMatchmakingPlayerCountParams& params,
    PgosDataCallback<GetConcurrentMatchmakingPlayerCountResult> result_callback);

Parameters:

Param	Type	Description
params	const GetConcurrentMatchmakingPlayerCountParams&	Matchmaking configuration name
result_callback	PgosDataCallback<GetConcurrentMatchmakingPlayerCountResult>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

Event Details

SetOnMatchmakingProcessChanged

The event will be triggered when the matchmaking process changed.

/**
 * OnSetOnMatchmakingProcessChanged:
 * The event will be triggered when the matchmaking process changed.
 * 
 * @param event Event result.
 */
void SetOnMatchmakingProcessChanged(
    const MatchmakingProcessChangedEvt& event);

Parameters:

Param	Type	Description
event	const MatchmakingProcessChangedEvt&	Event result.

Client Matchmaking API Reference

API List​

Event List​

API Details​

GetCurrentMatchmakings​

StartMatchmaking​

StartMatchmaking_V2​

StartP2PMatchmaking​

CancelMatchmaking​

DescribeMatchmaking​

JoinMatchmaking​

RejectMatchmaking​

AcceptMatchedBattle​

RejectMatchedBattle​

GetConcurrentMatchmakingPlayerCount​

Event Details​

SetOnMatchmakingProcessChanged​

API List

Event List

API Details

GetCurrentMatchmakings

StartMatchmaking

StartMatchmaking_V2

StartP2PMatchmaking

CancelMatchmaking

DescribeMatchmaking

JoinMatchmaking

RejectMatchmaking

AcceptMatchedBattle

RejectMatchedBattle

GetConcurrentMatchmakingPlayerCount

Event Details

SetOnMatchmakingProcessChanged