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
OnPlayerSessionChanged	The event will be triggered when the player session state changed.
OnPlayerBanned	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.
OnTitleRegionClosed	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.
OnEventChannelStatusChanged	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.
OnIntoLoginQueue	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.
OnLoginQueueUpdated	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 ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void LoginPGOS(
    const FPgosClientLoginPGOSParams& Params,
    TFunction<void(const FPgosResult& Ret, const FPgosClientAuthenticationInfo* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosClientLoginPGOSParams&	Request parameters for login PGOS.
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosClientAuthenticationInfo* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

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.
 */
FString MyPlayerID() const;

Parameters:

(No parameters)

Return: FString

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.
 */
FString MyAuthTicket() const;

Parameters:

(No parameters)

Return: FString

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 AccountOpenId Open id of the logged in account service.
 * @param Accountoken Token of the open id.
 * @param ExtraParam Extra parameter for the account service. For example, INTLSDK account service: extra_param["channel_id"]="4"; // 4 means Facebook.
 * @param ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void UpdateAccountToken(
    const FString& AccountOpenId,
    const FString& Accountoken,
    const TMap<FString, FString>& ExtraParam,
    TFunction<void(const FPgosResult& Ret)> ResultCallback) const;

Parameters:

Param	Type	Description
AccountOpenId	const FString&	Open id of the logged in account service.
Accountoken	const FString&	Token of the open id.
ExtraParam	const TMap<FString, FString>&	Extra parameter for the account service. For example, INTLSDK account service: extra_param["channel_id"]="4"; // 4 means Facebook.
ResultCallback	TFunction<void(const FPgosResult& Ret)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

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 ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void LogoutPGOS(
    const FPgosClientLogoutPGOSParams& Params,
    TFunction<void(const FPgosResult& Ret)> ResultCallback) const;

Parameters:

Param	Type	Description
Params	const FPgosClientLogoutPGOSParams&	Request parameters for logout PGOS.
ResultCallback	TFunction<void(const FPgosResult& Ret)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

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 ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void ReLoginPGOS(
    TFunction<void(const FPgosResult& Ret, const FPgosClientAuthenticationInfo* Data)> ResultCallback) const;

Parameters:

Param	Type	Description
ResultCallback	TFunction<void(const FPgosResult& Ret, const FPgosClientAuthenticationInfo* Data)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

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 ResultCallback The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.
 */
void QuitLoginQueue(
    TFunction<void(const FPgosResult& Ret)> ResultCallback) const;

Parameters:

Param	Type	Description
ResultCallback	TFunction<void(const FPgosResult& Ret)>	The result callback after the API execution ends, and it will be called in the GAME THREAD. For lifetime safety, it is recommended to use the CreateWeakCallback provided in PgosSDKCpp.h to create a lambda bound to an UObject.

Return: void

Event Details

OnPlayerSessionChanged

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

/**
 * OnPlayerSessionChanged:
 * The event will be triggered when the player session state changed.
 * 
 * @param Event Event result.
 */
DECLARE_MULTICAST_DELEGATE_OneParam(FOnPlayerSessionChanged, const FPgosClientPlayerSessionChangedEvt& /*Event*/);
FOnPlayerSessionChanged& OnPlayerSessionChanged() { return PlayerSessionChangedDelegate; }

Type Reference:

• FPgosClientPlayerSessionChangedEvt

OnPlayerBanned

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.

/**
 * OnPlayerBanned:
 * 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.
 */
DECLARE_MULTICAST_DELEGATE_OneParam(FOnPlayerBanned, const FPgosClientPlayerBannedEvt& /*Event*/);
FOnPlayerBanned& OnPlayerBanned() { return PlayerBannedDelegate; }

Type Reference:

• FPgosClientPlayerBannedEvt

OnTitleRegionClosed

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.

/**
 * OnTitleRegionClosed:
 * 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.
 */
DECLARE_MULTICAST_DELEGATE_OneParam(FOnTitleRegionClosed, const FPgosClientTitleRegionClosedEvt& /*Event*/);
FOnTitleRegionClosed& OnTitleRegionClosed() { return TitleRegionClosedDelegate; }

Type Reference:

• FPgosClientTitleRegionClosedEvt

OnEventChannelStatusChanged

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.

/**
 * OnEventChannelStatusChanged:
 * 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.
 */
DECLARE_MULTICAST_DELEGATE_OneParam(FOnEventChannelStatusChanged, const FPgosClientEventChannelStatusChangedEvt& /*Event*/);
FOnEventChannelStatusChanged& OnEventChannelStatusChanged() { return EventChannelStatusChangedDelegate; }

Type Reference:

• FPgosClientEventChannelStatusChangedEvt

OnIntoLoginQueue

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.

/**
 * OnIntoLoginQueue:
 * 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.
 */
DECLARE_MULTICAST_DELEGATE_OneParam(FOnIntoLoginQueue, const FPgosClientIntoLoginQueueEvt& /*Event*/);
FOnIntoLoginQueue& OnIntoLoginQueue() { return IntoLoginQueueDelegate; }

Type Reference:

• FPgosClientIntoLoginQueueEvt

OnLoginQueueUpdated

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

/**
 * OnLoginQueueUpdated:
 * The event will be triggered after periodically polling the login queue status.
 * 
 * @param Event Event result.
 */
DECLARE_MULTICAST_DELEGATE_OneParam(FOnLoginQueueUpdated, const FPgosClientLoginQueueUpdatedEvt& /*Event*/);
FOnLoginQueueUpdated& OnLoginQueueUpdated() { return LoginQueueUpdatedDelegate; }

Type Reference:

• FPgosClientLoginQueueUpdatedEvt