Concepts

Here we list the basics to get you started with the MDK.

Based on the context, we usually refer to a Moment in two different ways:

  • An interaction provided during an Event for a limited amount of time (see stagecast.io or the organizer dashboard);

  • The Web/Mobile App that defines that interaction (developers).

In the context of this docs, creating a Moment means creating a (HTML/CSS/Js) WebApp that will be related to a specific Stagecast Moment type (ie. an interaction type). Quiz, Lottery, Collage, are all different types of interaction (ie. Moments).

The WebApp must interact with the Stagecast backend and implement some concepts though the Moment Development Kit (MDK). It could be implemented in vanilla Javascript, or with libraries and frameworks.

Progressive Web Apps (PWA) are good candidates for becoming "Moments".

If you want to get your hands dirty right away, go to section API Reference.

Introduction

The responsible person for an event creates Stagecast Events for which she configures different Moment Classes.

A Moment Class is an abstract representation of the HTML-based app that you are about to develop. The moment class can be customized though a configuration page. The configuration data is what is sent at runtime to your HTML-based app before the onConfigReceived is called. Besides the configuration data, the Moment Class model includes other basic information inherited from another entity called Template.

The Template is the manifest of you HTML-based app. 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 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. 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.

During its life, a moment can generate images, audio files, videos etc. These media are generically referred to as Content and have a unified upload/download API.

A Moment can also persist and access a State for each User that can be retrieved even after the moment has ended.

All this structure seems extremely complex and probably an overkill, but there are reasons for that you don't have to worry about as everything happens under hood.

You only have to keep in mind the following:

  1. If you want to access the configuration data provided by the organizer, access the MomentClass.

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

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

  4. If you want to implement communication between different users in the same moment, you can use the messaging apis.

Moment

The Moment is the instance of your application that runs in specific 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.

MomentClass

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 user. These parameters are set in the Moment Configuration Page (web-platform) and stored in the MomentClass.

{
name: 'moment class name',
created: 123455678, // timestamp in MS
custom: {
// ... the developer data
}
}

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

Content

Contents are media files like images, videos etc. They have a unique id and can be fetched via the CDN.

User

The user is the entity that interacts with the Moment. It is identified by its mail and a time-based token. It can be either a Guest user or a registered user.

Guest users are those that haven't signed up to Stagecast as they are users of Wrapper Applications importing the Stagecast Feed. Regular users are simply those who have a Stagecast account.

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.