Concepts
Before implementing a "Moment", it is important to know what a Moment is and what it needs in order to work. Here we explain the basic concepts to onboard you onto the Stagecast system.
Last updated
Before implementing a "Moment", it is important to know what a Moment is and what it needs in order to work. Here we explain the basic concepts to onboard you onto the Stagecast system.
Last updated
Based on the context, we usually refer to a Moment in two different ways:
An interaction provided during an Event (sport event, concert etc..) for a limited amount of time (see stagecast.io or the organizer dashboard);
The Web/Mobile App that makes that interaction possible (developers).
In the context of this docs, creating a Moment means creating a (HTML/CSS/Js) WebApp that will implement a specific interaction type. Quiz, Lottery, Collage, are all different types of interaction (ie. Moments).
The WebApp must interact with the Stagecast backend and make use of some entities though the Moment Development Kit (MDK). The WebApp could be implemented in vanilla Javascript, or with libraries and frameworks like Vue.js or React.js.
If you prefer to get a hand-on understanding, you can go directly to the Tutorial Section and get back here afterwards.
The following paragraph describes how we usually explain how to our customers (the event organizers) the functioning of our system:
Once an Event has been created, you will be able to open the Moment Store and select one or more Moments and configure them. The moment that you have configured will be available in the Moment Launchpad. If you want your Moment to be sent to the Event attendee, click on "launch". When the you want to stop the interaction, click on "stop".
The event organizer thinks that she is working only with Moments, but what actually happens behind the curtains is the following:
Once an Event has been created on the Stagecast Platform, the organizer can go to the Store and browse though the different available Templates and select one in order to configure it. When the organizer opens the configuration window, she will be prompted with many different configuration boxes (sposor logos, languages, etc...). These boxes are displayed based on the information included in the Template and the template form definitions.
Once the user saves the changes, all the information provided by the even organizer will be included in a newly-created "Moment Class". Basically a Moment Class is a configured version of a Template. The Moment Class specifies information like the selected code version, the language of the moment, the notification message etc...
What the event organizer sees in the launchpad, are Moment Classes. When she clicks "Launch" the backend generates an instance of that Moment Class, the Moment. The Moment inherits some information from the Moment Class and add some additional properties like the creation time and an id to reserve a slot of space in the backend. This slot of space is where to persist the User Event Attendee state .
From a Moment Class the event organizer can launch as many Moments as she likes. Each of them will have a different creation time and a different slot for saving state.
Both Moment Class and Template are abstract representations of the HTML-based app (or WebApp) that you are about to develop. The Template is derived from the manifest of you WebApp and describes how your app can be configured. It contains information like supported languages, version of the code, supported plugins, the location of the source code bundles etc..The Moments Class is a configured instance of the Template that can be created in the Store configuration page. For example, it doesn't define what languages are supported, but it tells the specific language the code should use.
A part of the Moment Class configuration data is what is sent at runtime to your WebApp before the MDK.onConfigReceived is called. The Moment Class always refers to a specific Template version and it is the entity that you see in the event Launchpad. From a Moment Class, the organizer can launch and stop one or more Moments.
The Moment is an instance of a Moment Class at a given point in time with a time duration and validity. It is the entity that tells the Stagecast integrations (Join.stagecast.se or Stagecast App) they must run your WebApp. The WebApp will then fetch the MomentClass and the Moment to know what configurations it must apply (change the language, the background color, the theme etc...). Throughout the course of a Stagecast Event more Moments can be launched from the same Moment Class, but no more than one can be active at the same time for the same Moment Class.
By interacting with your WebApp while a Moment is active, the event attendee (the Moment user) can generate images, audio files, videos etc. These media are generically referred to as Content and have a unified upload/download API.
The event attendee can also create some user data that you might want to persist in order to reuse it (eg. the user submits its name and gets a score after playing a game). The MDK allow you to persist these information in a backend key-value store (the user state) accessible by the user. The state can be retrieved even after the moment has ended.
The Stagecast Event is our internal representation of an Event that is being organized. An Event is anything that has a start and end time and requires the gathering of some people. Example events could be concerts, festivals, football matches, live streams, gala dinners, conferences etc...
In general, when someone wants to gather people and let them use the Stagecast Moments, she must first create an Event entity through the Stagecast Web Platform.
Whenever you create Prizes, Quizzes, Moments or Moments Classes, they must belong to an Event and can be used it that Event only.
The Template is the entity that describes a WebApp and how it must be configured. It also specifies the location of the source code. The Template can be considered as the manifest for your WebApp (and in fact it is derived from the WebApp manifest.json).
The manifest is important for the Mobile outlets (Stagecast App, WebView Integration or Browser) as it contains information such as: location of the app code bundle, the bundle name, the bundle version, the developer info, the display specifications etc.
The Moment Class always refers to a specific Template version and it represents a configured instance of the Template.
The MomentClass is the base model the Moment inherits from. It is usually the holder of configurations that are then applied to the Moment code.
One, for example, could create an application that can be configured dynamically based on the parameters provided by the event organizer. These parameters are set in the Moment Configuration Page (web-platform) and stored in the MomentClass.
These parameters are accessed by the Application and can be used to display a custom logic. For example, let's suppose you are creating an Application - running in a Moment - that shows a Title and many circles of different sizes. You might want to make the Title and the circles sizes dynamic and customizable. If so, you only have you use variables and specify them in the custom object. This simple procedure will allow you to set custom values for your variables in the configuration page (web platform).
The Moment is the instance of your application that runs in specific Event (see Stagecast Event) for a specific duration (although there are moments with no duration, but they are out of the scope of this documentation, for now). A Moment has a start time (creation time) and a stop time, during this period, the Moment is it considered active, whereas passive when stopped.
The most relevant parameters are
The event attendee (generally referred to as "user") is the person that interacts with the Moment though a mobile device. It is identified by its mail and a time-based token. It can be either an anonymous, guest or a registered attendee.
A Moment can't function without an event attendee (user). Wherever the Moment runs (Stagecast App or join.stagecast.io integration) the Moment will always refer to one of the above-mentioned user types.
There is virtually no difference between the three types, but we can try to define them as follows:
Guest/anonymous users are those that haven't signed up to Stagecast as they are users of wrapper Applications of join.stagecast.io. They get assigned a randomly-generated email and password. These users don't have name, surname, birth date or gender.
Regular users are simply those who have a Stagecast account and have provided information such as name, surname etc...
While using a Moment, the event attendee can persist some information that can be fetched when reloading the Moment. Technically, we say that each user has allocated a slot of space for each Moment. This slot is called state and can be updated as many times as one wishes.
When the moment is created, the state of each user is undefined and any request to a specific user state returns either a 404 - Not Found error or an empty/null object: both cases have to be verified when developing a custom Moment.
The global state is a huge object that gathers all the user states. The object can be read by anybody so the single user state is only writable by the state owner, but it's not private as it can be read by anybody.
The global state has the following shape:
Contents are media files like images, videos etc. They have a unique id and can be fetched via the CDN.
The structure of a content is usually the following:
You only have to keep in mind the following:
If you want to access the configuration data provided by the organizer, access the MomentClass.
If you want to know if you code is active, if you want to synchronize devices or have information about the start and the end of a moment (perhaps to display different screens), you can refer to the Moment.
If you want to persist some data for a specific user (for example: the answers she has given to a poll) you can use the State apis.
If you want to implement communication between different users in the same moment, you can use the messaging apis.
