Stagecast
Stagecast
Stagecast Integration API
Stagecast Quiz API
Stagecast Prizes API
Stagecast Quest API
Powered by GitBook

Stagecast Integration API

Version 1.0

Moment discovery

get
Polling For Active Moments

https://d5q8k8cx63nj4.cloudfront.net/api/events/:eventId/moments/poll
Polls all the currently active moments for a specific event.
Request
Response
Request
Path Parameters
eventId
required
string
The event id. It is a uuid string on the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX, such as F5D6E9D6-5F1E-4A43-8348-0DA8BBAA29AF. You can find it in the address bar of your browser when you navigate to your event in the Stagecast web console (https://stagecast.se/dashboard/events/:eventId\)
Response
200: OK
A list of currently active moments or an empty list if there are none.
[{"triggeredBy":"manual","rec...}, ...]

Note: You may use stagecast.se as host for development tests but please use our CDN host d5q8k8cx63nj4.cloudfront.net for production.

get
Get the moment class of a moment

https://d5q8k8cx63nj4.cloudfront.net/api/momentClasses/:momentClassID
In order to retrieve moment configuration data you can fetch the moment class of a moment via its moment class ID. The moment class ID is found in the field "class" in the moment objects your retireve in the poll request above.
Request
Response
Request
Path Parameters
momentClassID
required
string
The moment class ID, as retrieved inside the moment objects in the polling method above
Response
200: OK
{"name": "my custom moment name", ...other data}

get
Receiving moment launch notifications from Stagecast backend

wss://stagecast.se/api/events/:eventId/ws
If you want to immediately be notified of moment launches via a notification, such as if you would like your backend to send out a firebase push notification, you can implement a service that connects to the Stagecast backend via its websocket interface.
Request
Response
Request
Path Parameters
eventId
required
string
The ID of your event
Response
200: OK
When connected to the websocket there will be messages like the following when a moment is launched. The "id" field is the moment ID that can be used to open the moment in the "open specific moment" API below. The "message" field holds the notification message you have configured when configuring the moment in the Stagecast web console. Type is either "start" or "stop" depending on if the moment was started or stopped.
{
    "type": "start",
    "triggeredBy": "manual",
    "title": "Quiz",
    "name": "quiz",
    "message": "User defined message (configured in Stagecast web)",
    "isInteractive": true,
    "isFeedContent": false,
    "id": "ABB5F8FC-F1E4-4F94-986A-72F7747797D8",
    "icons": ["https://d2cb7i0wbc0znj.cloudfront.net/api/content/FAD2C4A1-BC4E-46AE-B2DD-F601F769EEBF"],
    "event": "5041ED9C-9B09-4F94-8A44-F9E84B26C814",
    "duration": 5400000,
    "created": 1579196250809,
    "class": "3108B8FE-DF9A-4509-9CCB-E054F1485795"
}

Sample Code Snippets

JS
JS
const ws = new WebSocket('wss://stagecast.se/api/events/youreventid/ws')
ws.addEventListener('message', function (event) {
   console.log('moment notification received', JSON.parse(event.data))
})

Note: There is no guarantee that the Stagecast websocket interface will be always up. We might restart it at any time and also take it down for longer maintenance windows or the connection could be disrupted because of network errors. Therefore, any service that relies on being connected to the websocket interface needs to handle disconnection and errors by trying to periodically reestablishing the connection when it fails.

Opening moments in app webview

Note: When you integrate Stagecast into your App WebView, make sure to enable the support for window opening (more on this topic here and here). In general, Moments provide fallbacks in case a link cannot be opened on the native browser, but still, we encourage to add the support to ensure the best user experience possible.

get
Open most recent moment

https://stagecast.se/api/web/events/:eventId/:deviceId
This is the URL you give the web view in your app once a moment is launched. The eventId parameter is the identifier of the event. Loading this URL in a web view will load the most recent active moment. The deviceId in the path is some unique string.Some moments, such as voting, relies on the fact that people have some unique identifier. Therefore it is recommended that the app generates a URL-friendly deviceId, store it in persistent storage on the phone and use the same deviceID for each web view opening. This is to give a (at least weak) guarantee that a user will use the same identity for each opening of the moment and may not vote several times (in the case of the voting moment for instance).
Request
Response
Request
Path Parameters
eventId
required
string
The id of the stagecast event you are hosting.
deviceId
required
string
An identifier for the user.
Headers
Host
required
string
stagecast.se
Content-Type
optional
string
application/json
Query Parameters
meta
optional
string
A base64-encoded string that will be attached to the user
Response
200: OK
...whatever webview code there is

The eventId can be found in the web frontend on https://stagecast.se/login for your created event. Look in the URL path once you have navigated to your event - it is some uuid string such as F5D6E9D6-5F1E-4A43-8348-0DA8BBAA29AF or similar - and replace :eventId in the request above with the uuid string you find.

Sample Code Snippets

Swift
Swift
import UIKit
import WebKit
class ViewController: UIViewController {
    @IBOutlet weak var webView: WKWebView!
    override func viewDidLoad() {
        super.viewDidLoad()
        let myURL = URL(string:"https://stagecast.se/api/web/events/F5D6E9D6-5F1E-4A43-8348-0DA8BBAA29A/my-device-id")
        let myRequest = URLRequest(url: myURL!)
        webView.load(myRequest)
    }
}

get
Open a specific moment

https://stagecast.se/api/web/moments/:momentId/:deviceId
If you have polled for active moments or received the moment ID through the websocket notification interface and therefore know the ID of an active moment you want to open, you can open a web view to this specific moment directly even if it is not the most recently launched moment.
Request
Response
Request
Path Parameters
momentId
required
string
The moment ID of the active moment
deviceId
required
string
The identifier of the user
Query Parameters
meta
optional
string
A base64-encoded string that will be attached to the user
Response
200: OK
...whatever moment code there is...
Swift
Swift
import UIKit
import WebKit
class ViewController: UIViewController {
    @IBOutlet weak var webView: WKWebView!
    override func viewDidLoad() {
        super.viewDidLoad()
        let myURL = URL(string:"https://stagecast.se/api/web/moments/E5D6F9D6-5F2E-4A43-8348-0DA8BBAA29A/my-device-id")
        let myRequest = URLRequest(url: myURL!)
        webView.load(myRequest)
    }
}

Opening moments in any browser

get
Open most recent moment in a browser

https://join.stagecast.se/?code=:code
If you do not have an app but want people to join your moments from phone browsers you can redirect them to the stagecast.io homepage. There they can type in the 4-digit event code to join your most recent active moment. In case you are redirecting them from a website and you are in possession of the event code the direct link will be https://join.stagecast.se/?code=:codeAn example could be https://join.stagecast.se/?code=0001
Request
Response
Request
Query Parameters
code
optional
string
The unique 4-digits event code (not to be confused with the event id).
meta
optional
string
A base64-encoded string that will be attached to the user
Response
200: OK
...whatever webview code there is

Embed in your website

If you want to embed the Moments in your website. Just copy-paste the following code snippet where you want it to be displayed. You will have to replace the event code, with the one belonging to your event.

Depending on your implementation, you might have to edit the style property.

HTML
Example
HTML
<iframe
    id="stagecast-embed"
    allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; microphone; midi; vr"
    title="Stagecast Embedded"
    style="width:100vw; height: 100vh; margin: 0;"
    src="https://join.stagecast.se/?code=YOUR_EVENT_CODE">
</iframe>
Example
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Test Embed</title>
    <style>
        * {
            box-sizing: border-box;
        }
        body {
            margin: 0;
            padding: 0;
            overflow: hidden;
        }
    </style>
</head>
<body>
    <!-- The iframe is embedded in a page with a header -->
    <header style="height: 100px; width: 100%">
        <h1 style="margin: 0;">This is the page header</h1>
    </header>
    <iframe
        id="stagecast-embed"
        allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; microphone; midi; vr"
        title="Stagecast Embedded"
        style="width:100vw; height: calc(100vh - 100px); margin: 0; padding: 0; border: none;"
        src="https://join.stagecast.se/?code=1021">
    </iframe>
</body>
</html>

Missing a feature? We are working hard to build the best possible product for you. Please let us know in case you are missing a feature and we will be quick to respond. Thank you for your help!

​Fill out the Feature Request Form****

Next
Stagecast Quiz API
Last updated 4 months ago
Edit on GitHub
Contents
Moment discovery
get
Polling For Active Moments
get
Get the moment class of a moment
get
Receiving moment launch notifications from Stagecast backend
Sample Code Snippets
Opening moments in app webview
get
Open most recent moment
Sample Code Snippets
get
Open a specific moment
Opening moments in any browser
get
Open most recent moment in a browser
Embed in your website