Getting Started

A primer for the Stagecast Moment SDK. This client SDK is to be imported by your custom-made HTML-based Apps to interact with the Stagecast API Service and the Stagecast Messaging Service.

If you want to start coding right away, you can checkout the tutorial section and come back here later.

Introduction

The Moments SDK (also called MDK) is a client Javascript library that simplifies the development of Stagecast Moments (go to https://www.stagecast.io/product-overview for general overview) by offering a set of APIs and tools.

The basic functionalities are:

  1. Wrap the http calls made towards the Stagecast public API service;

  2. Wrap websocket messages to be sent via Stagecast Messaging Service;

  3. Offer utilities to inject ads/logos and translate page content into different languages;

  4. Provide some basic analytics library to track the user activity;

  5. Support for multiple environments to improve the testing flow both locally and on production. In particular, there are 3 main environments a moment can run:

    • preview mode;

    • staging mode;

    • production mode;

How To Use the MDK In Your Project

1. Import via CDN Link

Right now, the only supported way to import the Moment SDK, is via direct CDN link. 

<!-- Fetch the library code from the Stagecast CDN -->
<script src="https://stagecast.se/media/lib/mdk/stagecast.min.js"></script>

2. Create an instance of the SDK

const SDK = new Stagecast(configObj);

The constructor accepts an optional configuration object. However, most of the times, a major part of the configuration will be only accessible at runtime. In the latter case, the library can be instantiated without parameters.

3. Register a callback for the onConfigReceived event

A Moment is usually run inside a wrapper Webview or an iframe.

When the Moment gets loaded, the wrapper (ie. the Mobile App or an outer browser window) sends the runtime configuration to the Moment window.

Once the MDK has done instantiating, the onConfigReceivedevent is fired. This event is always called after the window.onload and can be considered as the entry point for your web app.

Of course, you can execute all the logic you want before the configuration is received. Usually the entry point is necessary to execute the runtime configurations that are only available only at last.

4. Example

A simple hello world Moment may look like the following:

<html>

  <head>
    <title>Test the SDK</title>
  </head>
  <body>
    <h1>My Awesome Moment</h1>
  </body>
  <!-- Js Scripts Import -->
  <script src="https://stagecast.se/media/lib/mdk/stagecast.min.js"></script>
  <script src="./main.js"></script>
</html>

You can have a view at some demos here: https://github.com/stagecast/moment-demos.

The Configuration Object

The configuration object schema looks like the following:

export interface SdkConfig {
  environment: string;
  token: string;
  userId: string;
  momentClassData: any;
  momentClassId: string;
  momentId: string;
  eventId: string;
  coordinates: string[];
  isGuest: boolean;
  isActive: boolean;
  isMomentActive: boolean;
  disableLogs: boolean;
}

Fields:

  • environment: the platform environment the Moment is running on (production or staging).

  • token: the user token to authenticate against the backend API service.

  • userId: the user email. It is generally used as a key to read and write to the Moment state. Each user has associated a bucket where the moment can save data.

  • momentClassData: the moment custom data provided at runtime and set by event organizer.

  • momentClassId: the moment class id. Each moment belongs to a moment class which defines its basic characteristics (name, category, version etc...). A moment can be seen as an instance of a MomentClass.

  • momentId: the moment id

  • eventId: the id of the event in which the moment are launched.

  • coordinates: the user latitude and longitude as provided by the device (if enabled by the user)

  • isGuest: flag that specifies whether the user is registered to stagecast or it is guest user. You can implement different custom logics based on this flag. However, most users will be guests, as we have dropped user registrations.

  • isActive: flag that specify whether the moment is currently live or has been stopped.

  • isMomentActive: same as above, kept for backward compatibility. Soon to be deprecated.

  • disableLogs: a flag used to disable all the window.console methods. 

document.getElementById("frame").contentWindow.postMessage({
"messageSource":"STAGECAST_SDK",
"config":{
  "environment": "staging",
  "userId": "user@stagecast.io",
  "token": "<temporary_user_token>",
  "momentClassData":{
    ...,
    // the property/values inside "custom" are totally 
    // up to the Moment developer
    "custom":{
      "contentList":[
         "7A955D3C-6E7C-42C5-BBD0-2B3196F91CFC"
       ],
      "gallerySize":100,
      "baseColorListHSL":[
        {"h":25,"s":0.7,"l":0.36},
        {"h":46,"s":0.7,"l":0.36},
        {"h":12,"s":0.7,"l":0.36}],
      "time": 10,
      "bigPicturePlacement": [0.5,0.5],
      "bigPictureSize": 0.6,
      "ads": ["A58885CD-F82A-443F-83E8-8CE81FB128F1"],
      "numAds": 2
    }
  },
  "momentClassId": "84B90A99-CF80-45A3-90A0-42E26ECEF633",
  "momentId": "34AB02BF-893A-4191-B4AB-DEE2E4931ECB",
  "created": 1573642962311,
  "eventId": "FC0C225F-CD0A-4B12-821C-0432DEC118CD",
  "disableLogs": false,
  "coordinates": ["0","0"],
  "isGuest": false,
  "isActive": true,
  "isMomentActive": true
}}, '*');

IMPORTANT NOTE

If the momentClassDatafield is left empty, the Moment SDK will try to fetch the data saved under themomentClassId key. This data is the one set in the moment configuration modal by the event organizer. If the field is not empty, SDK.getMomentData()will return a copy of the object specified in the configuration without calling any external API.

The configuration modal can be accessed via the Stagecast organizer web dashboard.

NextConcepts

Last updated