AirConsole Games Features
Improving your game engage
Persisting Player Data
17min
what is the persistent storage api? the persistent storage api enables your game to store data on behalf of your players to continue anywhere, anytime you can think of the persistent storage api as airconsoles version of a save game system that stores the data for players but with additional possibilities towards unique game designs that go well beyond traditional savegame capabilities before you get started there are different ways to implement persistent data storage for your game depending on your game design this gives you unique possibilities to use persistent data as a gameplay feature in your game design 1\ which players need to store and request part of the game state you can store and request data for every player in the game and selectively decide what to apply when and where (see working with data from multiple connected players below) you can store and request data for the player driving the session (see persisting data only for the controlling player below) when working with the persistent storage api, keep in mind that the storage limit is 1mb per uid per game! 2\ how do you want to use and persist the data in your game decide at what points you want to store the persistent data decide what happens when the owner of the persistent data leaves \ will future updates to the persistent data be stored for the leaving owner of the current game state? \ if not, will the players be able to continue but the general game state progress will no longer be persisteted, only player specific personal progress? \ or do you use the flexible capabilities to offer a unique approach? remember the players uids for which persistent data was requested for the lifetime of the usage of this game state to persist it for the correct player again working with data from multiple connected players airconsoles persistent storage api nature as key value based store gives you unique flexibility in deciding which controller contributes what information to the game worlds state this allows you to request and store data for multiple players in the same game and enable an optimal experience by combining the data in ways providing the best game experience example level unlocks are taken from the device with the most advanced state and to this device this part of the state is persisted example key level progress but every player can have their own unlocks (characters, gadgets, skins, abilities, features, ) which are stored based on their uid example key player progress in this example, the game requests and stores the progress of the world state, global quests or content unlocks in level progress while storing personalized player progress information in player progress when the players connect the game would request level progress for all players and select the most advanced state the game would also request player progress for all players and apply it to the corresponding player to unlock player specific aspects such a hybrid achives the best results, if the corresponding game experiennce and game progression is optimized for airconsole early in the game design and playtesting process, allowing you to create an experience your players want to come back to often and increasing your income persisting data only for the controlling player if you are working with the controlling player (using getmastercontrollerdeviceid() getmastercontrollerdeviceid() ) to load the game state, then you need to consider the different cases arising from this id changing as players join or leave the game getmastercontrollerdeviceid() getmastercontrollerdeviceid() can change during the runtime of the game due to connects / disconnects and you don't want to (re)load or store the data for the wrong player examples if a premium user connects to a game with non premium users only, then the master device will change to the premium device if the master device disconnects a different connected device will become master simply storing the persistent data to the now current master device would duplicate the state of the original players data to the new player while not updating the progress for the original player ! the game needs to remember the uid of the device for which the game state has been requested and used important considerations when not providing a uid to storepersistentdata / requestpersistentdata from airconsole api 1 9 0 and unity plugin 2 5 0 onwards, the possibility to call storepersistentdata / requestpersistentdata without providing a uid will be removed if you are not providing a uid to storepersistentdata / requestpersistentdata, then the data will be stored for the device that calls the function this is a convenience functionality when using it the persistent storage api on your controller you must not rely on this convencience when using it on the screen! the screen does not have a persistent uid (incognito mode, security features, plugins) due to this, the screen commonly is unable to restore persistent data reliably (browser and car in particular)! persisting data in web games the web examples assume that you have already set up your game similar to the pong example and have an object like var airconsole = new airconsole(); var airconsole = new airconsole(); storing persistent data implement function `handlepersistentdatastored` that does something based on the uid, for example a visual confirmation register an event listener to airconsole onpersistentdatastored = handlepersistentdatastored; airconsole onpersistentdatastored = handlepersistentdatastored; alternatively you can also directly declare the function airconsole onpersistentdatastored = function(uid) { // do something based on the uid }; airconsole onpersistentdatastored = function(uid) { // do something based on the uid }; after onready was invoked, call string uid = airconsole getuid(airconsole getdeviceid()); if(uid) { airconsole storepersistentdata("datakey", { keya "data a", keyb "data b" }, uid); } else { console error("master controller has no uid yet, was onready really invoked?"); } retrieving persistent data implement function `handlepersistentdataloaded` that processes the loaded persistent data register an event listener to airconsole onpersistentdataloaded = handlepersistentdataloaded; airconsole onpersistentdataloaded = handlepersistentdataloaded; alternatively you can also directly declare the function airconsole onpersistentdataloaded = function(data) { // do something now with the data }; airconsole onpersistentdataloaded = function(data) { // do something now with the data }; after onready was invoked, call something like var controllers = airconsole getcontrollerdeviceids(); var uids = controllers map(it => airconsole getuid(it)) || \[]; if(uids length > 0) { airconsole requestpersistentdata(uids); } persisting data in unity games please see examplebasiclogic cs for an example implementation storing persistent data implement an event handler `handlepersistentdatastored` that processes the received persistent data register an event listener to airconsole instance onpersistentdatastored += handlepersistentdatastored; airconsole instance onpersistentdatastored += handlepersistentdatastored; after onready was invoked, call string uuid = airconsole instance getuid(airconsole instance getdeviceid()); if(!string isnullorempty(uuid)) { jobject exampledata = new jobject(); exampledata add ("test", "data"); airconsole instance storepersistentdata("example data", exampledata, uid); } else { debug error("mastercontroller has no uid yet, was onready really invoked?"); } retrieving persistent data implement an event handler `handlepersistentdataloaded` that processes the received persistent data register an event listener to airconsole instance onpersistentdataloaded += handlepersistentdataloaded; airconsole instance onpersistentdataloaded += handlepersistentdataloaded; after onready was invoked, call something like list\<string> uids = new list\<string>(airconsole instance getcontrollerdeviceids() select(id => airconsole instance getuid(id)) where(id => !string isnullorempty(id))); if(uids count > 0) { airconsole instance requestpersistentdata(uids); } persisting data does not work, i have the following problem when reopening the game after storing the state, i can not get the stored state the uids in the simulator are not stable you will need to connect a real device to test this see the guides how to test your game and learn how to connect phones in unity guides for more information you can not store or retrieve a persistent state before the event onready was invoked in unity this would throw the airconsole notreadyexception