Stagecast Integration API
Version 1.0
getPolling For Active Moments
get
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.
getGet the moment class of a moment
get
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}
getReceiving moment launch notifications from Stagecast backend
get
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"}
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.
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.
getOpen most recent moment
get
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.
Swift
Swift
import UIKitimport WebKitclass 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)}}
getOpen a specific moment
get
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 UIKitimport WebKitclass 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)}}
getOpen most recent moment in a browser
get
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