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:
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:
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:
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:
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:
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:
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: