State service
The state service provides a key-value storage that an app can use to store internal states. It can store essential data needed for the app's functioning in its context—either accessible to all users, or confined to the specific user's context. These states are only accessible from their respective apps and can't be accessed using a different app or ad-hoc functions.
Alternatively, there is a storage system called the document service, which is a better fit for use cases where the information has the following characteristics
- Multiple users can collaborate on this data; a user can create, modify, or delete it using the app UI
- The data set is extensive (to learn more, visit Limitations)
Concepts
You need to know the following concepts to work with the state service.
User app states
You can use user app states to store information only relevant to a specific user and a specific app context. For example, storing minimal data concerning the configurable state of components used in your app. Thus, user app states can act as a "local storage" that transfers across sessions and devices used by that user.
App states
Be aware that all users of the app can read app states. If your use-case allows for a user-scoped state, then the user app state is preferable as best practice.
App states are accessible to all users; therefore, you can share specific states essential to the app's context. For example, you can create a workflow that fetches third-party data into your app function. Your app stores this information in its app state. All users of your app can then access this data.
There are also use cases to write an app state in browser code. For example, the app can allow the user to share some meta information, only relevant in the context of this app, with other users.
Limitations
Generic key-value-based state storage, where the key and value are simple strings, makes it possible for the app developer to manage the state design according to the specific needs of their app. For example, instead of using multiple small chunks of state, you can use one more significantly larger state as an alternative. In any case, listed below are the limits that the app needs to abide by - any operation violating them will result in an error:
- User app states: At most, 16 states are allowed per app for every user. Each user app state value may be at a maximum of 32 KB. A user app state key may be a maximum of 200 characters long.
- App states: The sum of all values per app can't exceed 50 MB. A single app state value may be at a maximum of 10 MB. An app state key may be a maximum of 200 characters long.
Of course, it's possible to delete states to avoid an imminent quota violation.
Reset states
It could be possible that an app mismanages its states by error and ends up in a situation where it's no longer functional. To remedy that situation, administrators (users with the policy "AppEngine - Admin" assigned) can clear all the app states and user app states of an app in the via the context menu entry "Reset state." In addition, any user can also trigger the clearance of their user app states.