Client PlayerAuth API Reference

PlayerAuth is the prerequisite of accessing PGOS services You need to use the player authentication service when the game needs to identify the player and manage the player session status of the player

API List

API	Description
LoginPGOS	Log in to gain access to the PGOS services, which will create a new player-session. The PGOS virtual server event event_player_login_pgos will be triggered. If login queue is enabled and the number of logged-in players has reached the max limit, the player will be put in the login queue. In this situation, the callback won't be called until the player is logged in or [QuitLoginQueue] is called. @see [SetOnIntoLoginQueue] and [SetOnLoginQueueUpdated].
MyPlayerID	Get the current player's id. If the player is not logged in, an empty string will be returned.
MyAuthTicket	Get the current player's PGOS authenticated ticket which can be used to authenticate the player via the HTTP Backed API. The ticket has a reliable validity period of 60 seconds. Please retrieve it from SDK when needed and avoid caching it. If the player is not logged in, an empty string will be returned.
UpdateAccountToken	Deprecated since <v0.21.0>. There is no longer a need for this API, and the game can remove the code that calls this API.
LogoutPGOS	Log out to end access to PGOS services, which will terminate the current player-session. The PGOS virtual server event event_player_logout_pgos will be triggered.
ReLoginPGOS	Try re-login to PGOS using the LoginPGOSParams cached in memory, this will create a new player session and trigger a PlayerSessionEvt::SessionStart if it runs successfully. It is generally recommended to call this API when the 'PlayerSessionEvt::SessionExpired_NetworkAbnormal' or 'PlayerSessionEvt::SessionExpired_TokenExpired' event occurs.
QuitLoginQueue	Quit the login queue. This can be called after receiving the [OnIntoLoginQueue] event), and it will cause the [LoginPGOS] to end too.

Event List

Event	Description
SetOnPlayerSessionChanged	The event will be triggered when the player session state changed.
SetOnPlayerBanned	The event will be triggered when the player is banned. it is recommended to show the player why he/she is banned, and then do something to limit the player's behavior, such as quitting the game. The ban reason can be obtained from the msg(JSON) of the callback.
SetOnTitleRegionClosed	The event will be triggered when the title region is closed. After the title region is closed, players who are not logged in cannot log in, and players who have logged in may be kicked offline after a specified time.
SetOnEventChannelStatusChanged	The event will be triggered when the event channel status has been changed. The Event Channel serves as a data pipeline for the PGOS backend to send event notifications (e.g., chat_messages/friend_requests) to the client. Its status can be influenced by factors such as API calls (e.g., login/logout) and fluctuations in the network environment. In certain scenarios, the event helps the game/player understand the possible reasons for PGOS/game service degradation.
SetOnIntoLoginQueue	The event will be triggered when the player is placed into the login queue. It is recommended to show the player the current queue position, and then do something to limit the player's behavior, such as trying to log in again.
SetOnLoginQueueUpdated	The event will be triggered after periodically polling the login queue status.

API Details

LoginPGOS

Log in to gain access to the PGOS services, which will create a new player-session. The PGOS virtual server event event_player_login_pgos will be triggered. If login queue is enabled and the number of logged-in players has reached the max limit, the player will be put in the login queue. In this situation, the callback won't be called until the player is logged in or [QuitLoginQueue] is called. @see [SetOnIntoLoginQueue] and [SetOnLoginQueueUpdated].

/**
 * Log in to gain access to the PGOS services, which will create a new player-session.
 * 
 * The PGOS virtual server event `event_player_login_pgos` will be triggered.
 * If login queue is enabled and the number of logged-in players has reached the max limit, the player will be put in the login queue.
 * In this situation, the callback won't be called until the player is logged in or [QuitLoginQueue] is called.
 * @see [SetOnIntoLoginQueue] and [SetOnLoginQueueUpdated].
 * 
 * @param params Request parameters for login PGOS.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void LoginPGOS(
    const LoginPGOSParams& params,
    PgosDataCallback<AuthenticationInfo> result_callback);

Parameters:

Param	Type	Description
params	const LoginPGOSParams&	Request parameters for login PGOS.
result_callback	PgosDataCallback<AuthenticationInfo>	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

MyPlayerID

Get the current player's id. If the player is not logged in, an empty string will be returned.

/**
 * Get the current player's id.
 * If the player is not logged in, an empty string will be returned.
 * 
 * @return The current player's id, valid after a successful LoginPGOS.
 */
pgos::pstring MyPlayerID();

Parameters:

(No parameters)

Return: pgos::pstring

The current player's id, valid after a successful LoginPGOS.

MyAuthTicket

Get the current player's PGOS authenticated ticket which can be used to authenticate the player via the HTTP Backed API. The ticket has a reliable validity period of 60 seconds. Please retrieve it from SDK when needed and avoid caching it. If the player is not logged in, an empty string will be returned.

/**
 * Get the current player's PGOS authenticated ticket which can be used to authenticate the player via the HTTP Backed API.
 * The ticket has a reliable validity period of 60 seconds. Please retrieve it from SDK when needed and avoid caching it.
 * If the player is not logged in, an empty string will be returned.
 * 
 * @return The current player's ticket, valid after a successful LoginPGOS.
 */
pgos::pstring MyAuthTicket();

Parameters:

(No parameters)

Return: pgos::pstring

The current player's ticket, valid after a successful LoginPGOS.

UpdateAccountToken

Deprecated since <v0.21.0>. There is no longer a need for this API, and the game can remove the code that calls this API.

Deprecated.

/**
 * Deprecated since <v0.21.0>.
 * There is no longer a need for this API, and the game can remove the code that calls this API.
 * [DEPRECATED!!!] UpdateAccountToken was declared deprecated.
 * 
 * @param account_open_id Open id of the logged in account service.
 * @param account_token Token of the open id.
 * @param extra_param Extra parameter for the account service. For example, INTLSDK account service: extra_param["channel_id"]="4"; // 4 means Facebook.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void UpdateAccountToken(
    const pgos::pstring& account_open_id,
    const pgos::pstring& account_token,
    const pgos::pmap<pgos::pstring, pgos::pstring>& extra_param,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
account_open_id	const std::string&	Open id of the logged in account service.
account_token	const std::string&	Token of the open id.
extra_param	const std::map<std::string, std::string>&	Extra parameter for the account service. For example, INTLSDK account service: extra_param["channel_id"]="4"; // 4 means Facebook.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

LogoutPGOS

Log out to end access to PGOS services, which will terminate the current player-session. The PGOS virtual server event event_player_logout_pgos will be triggered.

/**
 * Log out to end access to PGOS services, which will terminate the current player-session.
 * 
 * The PGOS virtual server event `event_player_logout_pgos` will be triggered.
 * 
 * @param params Request parameters for logout PGOS.
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void LogoutPGOS(
    const LogoutPGOSParams& params,
    PgosCallback result_callback);

Parameters:

Param	Type	Description
params	const LogoutPGOSParams&	Request parameters for logout PGOS.
result_callback	PgosCallback	The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.

Return: void

ReLoginPGOS

Try re-login to PGOS using the LoginPGOSParams cached in memory, this will create a new player session and trigger a PlayerSessionEvt::SessionStart if it runs successfully. It is generally recommended to call this API when the 'PlayerSessionEvt::SessionExpired_NetworkAbnormal' or 'PlayerSessionEvt::SessionExpired_TokenExpired' event occurs.

/**
 * Try re-login to PGOS using the `LoginPGOSParams` cached in memory, this will create a new player session and trigger a `PlayerSessionEvt::SessionStart` if it runs successfully.
 * It is generally recommended to call this API when the 'PlayerSessionEvt::SessionExpired_NetworkAbnormal' or 'PlayerSessionEvt::SessionExpired_TokenExpired' event occurs.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void ReLoginPGOS(
    PgosDataCallback<AuthenticationInfo> result_callback);

Parameters:

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

Return: void

QuitLoginQueue

Quit the login queue. This can be called after receiving the [OnIntoLoginQueue] event), and it will cause the [LoginPGOS] to end too.

/**
 * Quit the login queue.
 * This can be called after receiving the [OnIntoLoginQueue] event), and it will cause the [LoginPGOS] to end too.
 * 
 * @param result_callback The result callback after the API execution ends, and it will be called in an ASYNCHRONOUS CHILD THREAD.
 */
void QuitLoginQueue(
    PgosCallback result_callback);

Parameters:

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

Return: void

Event Details

SetOnPlayerSessionChanged

The event will be triggered when the player session state changed.

/**
 * OnSetOnPlayerSessionChanged:
 * The event will be triggered when the player session state changed.
 * 
 * @param event Event result.
 */
void SetOnPlayerSessionChanged(
    const PlayerSessionChangedEvt& event);

Parameters:

Param	Type	Description
event	const PlayerSessionChangedEvt&	Event result.

SetOnPlayerBanned

The event will be triggered when the player is banned. it is recommended to show the player why he/she is banned, and then do something to limit the player's behavior, such as quitting the game. The ban reason can be obtained from the msg(JSON) of the callback.

/**
 * OnSetOnPlayerBanned:
 * The event will be triggered when the player is banned.
 * it is recommended to show the player why he/she is banned, 
 * and then do something to limit the player's behavior, such as quitting the game.
 * The ban reason can be obtained from the msg(JSON) of the callback.
 * 
 * @param event Event result.
 */
void SetOnPlayerBanned(
    const PlayerBannedEvt& event);

Parameters:

Param	Type	Description
event	const PlayerBannedEvt&	Event result.

SetOnTitleRegionClosed

The event will be triggered when the title region is closed. After the title region is closed, players who are not logged in cannot log in, and players who have logged in may be kicked offline after a specified time.

/**
 * OnSetOnTitleRegionClosed:
 * The event will be triggered when the title region is closed.
 * After the title region is closed, players who are not logged in cannot log in, 
 * and players who have logged in may be kicked offline after a specified time.
 * 
 * @param event Event result.
 */
void SetOnTitleRegionClosed(
    const TitleRegionClosedEvt& event);

Parameters:

Param	Type	Description
event	const TitleRegionClosedEvt&	Event result.

SetOnEventChannelStatusChanged

The event will be triggered when the event channel status has been changed. The Event Channel serves as a data pipeline for the PGOS backend to send event notifications (e.g., chat_messages/friend_requests) to the client. Its status can be influenced by factors such as API calls (e.g., login/logout) and fluctuations in the network environment. In certain scenarios, the event helps the game/player understand the possible reasons for PGOS/game service degradation.

/**
 * OnSetOnEventChannelStatusChanged:
 * The event will be triggered when the event channel status has been changed.
 * The Event Channel serves as a data pipeline for the PGOS backend to send event notifications (e.g., chat_messages/friend_requests) to the client.
 * Its status can be influenced by factors such as API calls (e.g., login/logout) and fluctuations in the network environment.
 * In certain scenarios, the event helps the game/player understand the possible reasons for PGOS/game service degradation.
 * 
 * @param event Event result.
 */
void SetOnEventChannelStatusChanged(
    const EventChannelStatusChangedEvt& event);

Parameters:

Param	Type	Description
event	const EventChannelStatusChangedEvt&	Event result.

SetOnIntoLoginQueue

The event will be triggered when the player is placed into the login queue. It is recommended to show the player the current queue position, and then do something to limit the player's behavior, such as trying to log in again.

/**
 * OnSetOnIntoLoginQueue:
 * The event will be triggered when the player is placed into the login queue.
 * It is recommended to show the player the current queue position, 
 * and then do something to limit the player's behavior, such as trying to log in again.
 * 
 * @param event Event result.
 */
void SetOnIntoLoginQueue(
    const IntoLoginQueueEvt& event);

Parameters:

Param	Type	Description
event	const IntoLoginQueueEvt&	Event result.

SetOnLoginQueueUpdated

The event will be triggered after periodically polling the login queue status.

/**
 * OnSetOnLoginQueueUpdated:
 * The event will be triggered after periodically polling the login queue status.
 * 
 * @param event Event result.
 */
void SetOnLoginQueueUpdated(
    const LoginQueueUpdatedEvt& event);

Parameters:

Param	Type	Description
event	const LoginQueueUpdatedEvt&	Event result.