Cloud sessions provide a simple way to save data in the cloud, and to share data between different devices. Cloud sessions automatically synchronize the shared data between participants of the same cloud session.
To take advantage of cloud sessions, you need to do two things:
- Declare replicated data. This is done by creating a global variable, a table, or an index (see records), and then selecting the
replicatedradio button. Replicated variables, tables and indexes work just like regular variables, tables and indexes, except that their content is automatically synchronized and backed up in the cloud.
- Switch the cloud session (optional). Whenever you run a script with cloud data, it starts in a default session, called the "just-me" session`. Often, you may want to add a few lines of code to your script to switch to a different cloud session, such as the "everyone" session, or to let users switch to a cloud session of their choice. You can even create new sessions.
When running a script that uses replicated data, a special cloud icon is displayed near the top right corner of the screen. Underneath the icon, the status is displayed. If it says "connected", the current cloud session is connected to the server. If it says "offline", the script is operating with a locally cached copy. When connection is reestablished, the status automatically goes back to "connected", and all changes are synchronized.
Tap on the cloud icon to get more information about the current cloud session, such as the reason why a session is offline, or some indication of progress.
The data of a cloud session is stored in multiple places (locally cached on each participant's device, and in the cloud). Participants can keep working with cached cloud sessions even if they do not have any network connection.
Take a look at the following sample scripts to see cloud data in action.
Sample scripts written by the TouchDevelop team:
- cloud list - a simple list using cloud data
- quick vote - very simple voting app
- cloud paper scissors - real time matchmaking and gameplay of the classic game
- Cloud Square - age old game for keeping kids occupied at restaurants
- Cloud Checkers - thanks to lycan.999 for the initial version!
- instant poll - quickly polling an audience and displaying the responses as a grid of colors
- bird log - Log your bird sightings and share them with other people!
- contest voting - we'll keep this app around even after the voting period will have closed
- guess multi-player demo - demo of Cloud Game Selector library
Useful libraries created by the TouchDevelop team:
- Barrier user round - helps synchronize multiple players in a game with rounds
- Cloud Game Selector - join multi-player games in cloud sessions
Cool scripts written by TouchDevelop users:
Cloud Session Management
Each script comes with two predefined sessions:
- The "just-me" session. This session is selected based on the current script and user, and is meant to share data between all devices by the same user running the same script. Other users cannot connect to this session. The just-me session is the default session: when you first run a script, it starts in this session. The just-me session is deleted when the script is uninstalled - if the same script is reinstalled, a fresh just-me session is created.
- The "everyone" session. Everyone running the same script can connect to this session. This session is owned by the author of the script (who may choose to delete it). This session is selected based on the name of the script, and its author.
The easiest way to switch sessions is to bring up the session switching dialog. For example, you could call this every time your script starts, or you could call it whenever the user taps some button:
cloud data → switch sessions
In this dialog, the user has a number of options. They can connect to a predefined session, they can create new sessions, or they can enter to a session specified by a unique identifier.
You can specify what session you would prefer to switch to. For example, to switch to the everyone session:
cloud data → switch to session(cloud data → everyone session)
Note that the session dialog is still displayed to the user (at least the first time around), and the user may choose a different session than the one specified.
Other examples are:
cloud data → switch to session(cloud data → just me session)
cloud data → switch to session(cloud data → session of("bqsl0prcbbmuwe", "some title"))
In the latter form, the second argument is a "friendly title" to be displayed in the session switching dialog.
New sessions can be created either in the session dialog, or by calling the
var s := cloud data → create session("my new session", "shareable")
"my new session" is a title for the session, and "shareable" defines the access permissions. At this point, there are just three types of permissions:
- shareable sessions, as the name suggests, grant read and write access to absolutely everyone.
- private sessions grant read and write access to you only.
- broadcast sessions can be read by absolutely everyone, but can be written only by you.
You can share shareable and broadcast session ids with your friends so that they can connect to your sessions.
Sessions consume storage space on your local device and in the cloud. You can delete the sessions you own in the session switching dialog (tap the delete button twice). Currently, we do not support a script API for deleting sessions.
To clear the locally cached sessions for a script, go to the script properties dialog and choose "delete script data". This erases all locally stored information, but it does not erase the data that is stored in the cloud.
Working with cloud tables and indices
Synchronization of cloud tables and cloud indices happens automatically, but only at safe moments when your code is not running. In particular it may happen between events handler, during
time->sleep, before and after every script run, while your code is awaiting an async action.
Fields of cloud records have a few new properties:
test and set(supported for strings only) only writes a new value if the previous value in the cloud was empty; you should wait until this change becomes
trueonce the last write has been successfully transmitted to the cloud
You can also subscribe to a new event handler that will get invoked when cloud data has changed.
You may encounter the following limitations:
- limitations in the size of each individual cloud session
- limitations in the total size of all cloud sessions owned by you
We may impose such limitations because of size restrictions imposed by devices or browsers, and to maintain fair use of data by all users.
We are considering adding the following feature in future releases.
- export to Windows Azure, so that you can host your own cloud data in your exported apps without size limitations
- use cloud data in exported apps
- more fine-grained permission model for shareable sessions
- searchable public sessions
- list of users currently connected to a session