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.
}