Stagecast
Stagecast
Stagecast Integration 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
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

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
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
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=:code An example could be https://join.stagecast.se/?code=0001
Request
Response
Request
Path Parameters
code
optional
string
The unique 4-digits event code (not to be confused with the event id).
Response
200: OK
...whatever webview code there is

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

Last updated 6 days ago
Contents
Moment discovery
get
Polling For Active Moments
get
Receiving moment launch notifications from Stagecast backend
Opening moments in app webview
get
Open most recent moment
get
Open a specific moment
Opening moments in any browser
get
Open most recent moment in a browser