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].

/// <summary>
/// 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].
/// </summary>
/// <param name="pgos_params">Request parameters for login PGOS.</param>
public void LoginPGOS(LoginPGOSParams pgos_params, PlayerAuthDelegate0 callback);

Parameters:

Param	Type	Description
pgos_params	LoginPGOSParams	Request parameters for login PGOS.
callback	PlayerAuthDelegate0

Return: void

MyPlayerID

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

/// <summary>
/// Get the current player's id.
/// If the player is not logged in, an empty string will be returned.
/// </summary>
public string MyPlayerID();

Parameters:

(No parameters)

Return: string

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.

/// <summary>
/// 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.
/// </summary>
public string MyAuthTicket();

Parameters:

(No parameters)

Return: string

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.

/// <summary>
/// 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.
/// </summary>
/// <param name="account_open_id">Open id of the logged in account service.</param>
/// <param name="account_token">Token of the open id.</param>
/// <param name="extra_param">Extra parameter for the account service. For example, INTLSDK account service: extra_param["channel_id"]="4"; // 4 means Facebook.</param>
public void UpdateAccountToken(string account_open_id, string account_token, Dictionary<string, string> extra_param, PlayerAuthDelegate1 callback);

Parameters:

Param	Type	Description
account_open_id	string	Open id of the logged in account service.
account_token	string	Token of the open id.
extra_param	Dictionary<string, string>	Extra parameter for the account service. For example, INTLSDK account service: extra_param["channel_id"]="4"; // 4 means Facebook.
callback	PlayerAuthDelegate1

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.

/// <summary>
/// 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.
/// </summary>
/// <param name="pgos_params">Request parameters for logout PGOS.</param>
public void LogoutPGOS(LogoutPGOSParams pgos_params, PlayerAuthDelegate1 callback);

Parameters:

Param	Type	Description
pgos_params	LogoutPGOSParams	Request parameters for logout PGOS.
callback	PlayerAuthDelegate1

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.

/// <summary>
/// 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.
/// </summary>
public void ReLoginPGOS(PlayerAuthDelegate0 callback);

Parameters:

Param	Type	Description
callback	PlayerAuthDelegate0

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.

/// <summary>
/// Quit the login queue.
/// This can be called after receiving the [OnIntoLoginQueue] event), and it will cause the [LoginPGOS] to end too.
/// </summary>
public void QuitLoginQueue(PlayerAuthDelegate1 callback);

Parameters:

Param	Type	Description
callback	PlayerAuthDelegate1

Return: void

Event Details

OnPlayerSessionChanged

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

/// <summary>The event will be triggered when the player session state changed.</summary>
public event PlayerAuthDelegate2 OnPlayerSessionChanged;

Type Reference:

• PlayerAuthDelegate2

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.

/// <summary>
/// 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.
/// </summary>
public event PlayerAuthDelegate3 OnPlayerBanned;

Type Reference:

• PlayerAuthDelegate3

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.

/// <summary>
/// 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.
/// </summary>
public event PlayerAuthDelegate4 OnTitleRegionClosed;

Type Reference:

• PlayerAuthDelegate4

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.

/// <summary>
/// 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.
/// </summary>
public event PlayerAuthDelegate5 OnEventChannelStatusChanged;

Type Reference:

• PlayerAuthDelegate5

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.

/// <summary>
/// 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.
/// </summary>
public event PlayerAuthDelegate6 OnIntoLoginQueue;

Type Reference:

• PlayerAuthDelegate6

OnLoginQueueUpdated

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

/// <summary>The event will be triggered after periodically polling the login queue status.</summary>
public event PlayerAuthDelegate7 OnLoginQueueUpdated;

Type Reference:

• PlayerAuthDelegate7

All Delegates

public delegate void PlayerAuthDelegate0(PgosResult a0, AuthenticationInfo a1);
public delegate void PlayerAuthDelegate1(PgosResult a0);
public delegate void PlayerAuthDelegate2(PlayerSessionChangedEvt a0);
public delegate void PlayerAuthDelegate3(PlayerBannedEvt a0);
public delegate void PlayerAuthDelegate4(TitleRegionClosedEvt a0);
public delegate void PlayerAuthDelegate5(EventChannelStatusChangedEvt a0);
public delegate void PlayerAuthDelegate6(IntoLoginQueueEvt a0);
public delegate void PlayerAuthDelegate7(LoginQueueUpdatedEvt a0);

Type Reference:

• PgosResult
• AuthenticationInfo
• PlayerSessionChangedEvt
• PlayerBannedEvt
• TitleRegionClosedEvt
• EventChannelStatusChangedEvt
• IntoLoginQueueEvt
• LoginQueueUpdatedEvt