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:
establishedstate 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.
Session State Diagram
When SDK is initialized:
- If the user is not logged in, the SDK starts in the initial "
- If the user is already logged in, the SDK automatically resumes the logged-in session and immediately switches to the
When TS SDK is initialized, the session state always begins as
When logging in:
- If login succeeds, it moves to
- If login fails, it moves to
When logging out manually:
- It moves to
When the user is logged in, but the user is banned or deleted from the system.
- It moves to
The error code will be presented in
terminatedstate. Please refer to Error Handling for more details.
When token has expired:
- It moves to
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.
Observe 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:
Implement app navigation based on session state
For logging, the SDK requires
SessionHandler. SDK uses this object to communicate with the app when session handling is required. Currently,
SessionHandleris used for:
- Initiate access token renewal when it is about to expire or has expired.
A simple session handler
The code above shows a simple session handler. Please note that each function in
SessionHandlercan 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
sessionWillRenewAccessTokenmethod of the
During the renewal process, the SDK passes an
AccessTokenRenewalobject to the app. The app must call either one of the following methods on this object to complete the process.
Method on renewal object
Indicates the SDK to renew the access token without an auth token.
Indicates the SDK to renew the access token with an auth token. (Required for secure login)
Indicates the SDK to postpone renewal.
SDK will re-initiate access token renewal at a later time, but no sooner than 10 minutes.
The following code shows how the app can implement the
sessionWillRenewAccessTokenmethod by providing an auth token for renewal.
An example of access token renewal with auth token.