Session state is a key concept in the SDK that describes the authentication status of the client device. There are several session states that the SDK can be in, including:
notLoggedIn
establishing
established
tokenExpired
terminated
The established state is the normal and fully authenticated state in which the SDK is usable. The other states represent different stages of the authentication process or an error condition.
When SDK is initialized:
If the user is not logged in, the SDK starts in the initial "notLoggedIn" state.
If the user is already logged in, the SDK automatically resumes the logged-in session and immediately switches to the established state.
When TS SDK is initialized, the session state always begins as notLoggedIn.
When logging in:
If login succeeds, it moves to established state.
If login fails, it moves to notLoggedIn state.
When logging out manually:
It moves to notLoggedIn state.
When the user is logged in, but the user is banned or deleted from the system.
It moves to terminated state.
The error code will be presented in terminated state. Please refer to Error Handling for more details.
When token has expired:
It moves to tokenExpired state.
If the access token has expired, all network requests will fail. However, the SDK includes an automatic process for renewing the access token. As long as this process is implemented correctly, it is unlikely that the app will encounter this problem. Please refer to #session-handler for more details.
The SDK provides APIs for reading and observing the session state.
Session state is designed to align with the typical flow of an app. For example, developers can use the session state to guide app navigation, like this:
For logging, the SDK requires SessionHandler. SDK uses this object to communicate with the app when session handling is required. Currently, SessionHandler is used for:
Initiate access token renewal when it is about to expire or has expired.
The code above shows a simple session handler. Please note that each function in SessionHandler can be customized to your app logic.
When a user logs in to the SDK for the first time, an access token is issued that is valid for 30 days.
If the access token is about to expire or has already expired, the SDK automatically initiates the renewal process through the sessionWillRenewAccessToken method of the SessionHandler.
During the renewal process, the SDK passes an AccessTokenRenewal object to the app. The app must call either one of the following methods on this object to complete the process.
The following code shows how the app can implement the sessionWillRenewAccessToken method by providing an auth token for renewal.
| Method on renewal object | |
|---|---|
renew()
Indicates the SDK to renew the access token without an auth token.
renewWithAuthToken(...)
Indicates the SDK to renew the access token with an auth token. (Required for secure login)
unableToRetrieveAuthToken()
Indicates the SDK to postpone renewal.
SDK will re-initiate access token renewal at a later time, but no sooner than 10 minutes.