JSON Database Storage
Learn more about storing persistent user data with HYPLAY's state storage systems.
Overview
HYPLAY provides a complete, out of the box database-like system to store non-relational data specific to your app, each unique user of your app, or any arbitrary key lookup structure you may set yourself. This simplifies a number of complexities that come with trying to handle persisted user data for game backends, frontend only apps, and more.
This system is simply referred to as app state.
Permissions
Data visibility permissions are baked into this system. App state supports 3 permissioned types that can be independently or combinatorially set. These permission types are publicState
, protectedState
and privateState
data.
publicState
data can be set by the authorized user or the application using the user's session access token or app's secret key. Anyone can read a user's public state data for an application. This is useful for storing things like user settings or preferences.protectedState
data can only be set by the application using it's secret key. Anyone can read a user's protected data. Protected data is useful for app controlled and verified data. This could be things like a user's experience points, hit points, level, attack power, inventory, and much more.privateState
data can only be set by the application using it's secret key. Only the application can read a user's private data. Private data is useful when your application needs to associate sensitive information with a user that is used internally and should only be accessible by your app.
Setting & Getting App State
You can set state unique to your application with the set app state endpoint: https://docs.hyplay.com/reference/setappstate
State specific to your application is useful for any global parameters required by your app or game. Public and protected application specific state can be retrieved by any user.
To set state using the set app state endpoint, provide your app's id, and the x-app-authorization
header, as well as any public, protected or private state data you'd like to set for your application.
To get an app's public and protected state, use the get app state endpoint and provide the target app id: https://docs.hyplay.com/reference/getappstate
You an also get an application's private state by providing the app id and the x-app-authorization
header of the app to the get app state endpoint as well: https://docs.hyplay.com/reference/getappstate
Setting & Getting App User State
You can set state unique to a user of your application with the set app state endpoint: https://docs.hyplay.com/reference/setappstate
State specific to a user of your application is useful for storing data about a user's details, progress for a game, preferences, and more. Public and protected user specific state can be retrieved by any user.
To set state using the set app state endpoint, you can provide your app's id, and the x-session-authorization
header for the user you want to set state for. Alternatively, you can instead provide your app's id and the hyplay user id as the lookup key
you want to set state for.
To get a user's public and protected state, use the get app state endpoint and provide the target app id, as well as the user's id as the lookup key
: https://docs.hyplay.com/reference/getappstate
Setting & Getting App Key State
You can set state unique to an arbitrary key you define with the set app state endpoint: https://docs.hyplay.com/reference/setappstate
State specific to an arbitrary key is useful for many situations and is intended to be flexible. State for keys can only be set by the application. Public and protected key specific state can be retrieved by any user.
To set state using the set app state endpoint, you can provide your app's id, the x-app-authorization
header, they key
you want to set for, and the public/protected/private state to be set.
To get a key's public and protected state, use the get app state endpoint and provide the target app id, as well as the key
to retrieve data for: https://docs.hyplay.com/reference/getappstate
Deep Merging vs. Overwrites
By default, when setting state on an app, user or key that already has existing state, a deep merge will be performed between the previous and new state.
For example, let's say we have an existing state of...
{
"publicState": {
"volume": 100,
"bass": {
"front": 10,
"rear": 0
},
"songs": [ "who am i", "welcome to the jungle" ]
},
"protectedState": {},
"privateState": {}
}
And we want to set the following state:
{
"publicState": {
"bass": {
"front": 3,
},
"songs": [ "whats my name" ]
}
}
Then, with the deep merge approach, our new reconciled state that is set would become:
{
"publicState": {
"volume": 100,
"bass": {
"front": 3,
"rear": 0
},
"songs": [ "whats my name" ]
},
"protectedState": {},
"privateState": {}
}
You'll notice that our songs array didn't merge. This is because the default merge behavior will always overwrite the an array type value with the new array provided, because there is no standard mechanism for existing a change to an existing array item or a newly provided one.
Lastly, if you want to completely overwrite the state type provided, whether it be publicState
, protectedState
and/or privateState
state, you can set the overwrite
field to true
when using the set app state endpoint: https://docs.hyplay.com/reference/setappstate
Non-Existent State & Keys
If you attempt to retrieve state for a app, user id, or key that has not previously had any state set. You'll receive an empty state response back from the get app state endpoint.
This response is structured as:
{
publicState: {},
protectedState: {},
privateState: {} // if no x-app-authorization provided, private state property is omitted.
}
Updated about 1 month ago