> For the complete documentation index, see [llms.txt](https://dev-stagecast.gitbook.io/stagecast/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://dev-stagecast.gitbook.io/stagecast/readme.md).

# Stagecast Integration API

## Activation discovery

## Polling For Active Activations in a workspace

<mark style="color:blue;">`GET`</mark> `https://d21pr33ep1h6mu.cloudfront.net/api/workspaces/:workspaceId/activations/`

Polls all the currently active activations for a specific workspace.

#### Path Parameters

| Name        | Type   | Description                                                                                                                                                                                                                                                                                                                       |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| workspaceId | string | The workspace 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 workspace in the Stagecast web console (<https://console.stagecast.io/workspaces/:workspaceId/rooms/:roomId/>) |

{% tabs %}
{% tab title="200 " %}

```
[{"_id":"abc-123","name":"Live Quiz"}, ...]
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Note: You may use **console.stagecast.io** as host for development tests but please use our CDN host **d21pr33ep1h6mu.cloudfront.net** for production.
{% endhint %}

## Opening activations in app webview

{% hint style="info" %}
Note: When you integrate Stagecast into your App WebView, make sure to enable the support for window opening (more on this topic [here](https://stackoverflow.com/questions/9147875/webview-dont-display-javascript-windows-open) and [here](https://stackoverflow.com/questions/33190234/wkwebview-and-window-open)).
{% endhint %}

## Open an activation

<mark style="color:blue;">`GET`</mark> `https://console.stagecast.io/api/open`

This is the URL you give the web view in your app once an activation is launched. If you do not specify the activationId it will load the **currently active** activation. The deviceId in the path is some unique string.

Some activations, 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 activation and may not vote several times (in the case of the voting activation for instance).

#### Query Parameters

| Name         | Type   | Description                                                                                                               |
| ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| activationId | string | The id of the stagecast activation (if you want to open an explicit one - omit if you want to open just the current one). |
| deviceId     | string | An identifier for the user.                                                                                               |
| code         | string | The room code as found in the stagecast web console                                                                       |
| meta         | string | A base64-encoded string that will be attached to the user                                                                 |

#### Headers

| Name         | Type   | Description          |
| ------------ | ------ | -------------------- |
| Host         | string | console.stagecast.io |
| Content-Type | string | application/json     |

{% tabs %}
{% tab title="200 " %}

```
...whatever webview code there is
```

{% endtab %}
{% endtabs %}

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

#### Sample Code Snippets

{% tabs %}
{% tab title="Swift" %}

```swift
import UIKit
import WebKit
class ViewController: UIViewController {
    @IBOutlet weak var webView: WKWebView!
    override func viewDidLoad() {
        super.viewDidLoad()
        let myURL = URL(string:"https://console.stagecast.io/api/open?code=abc123&deviceId=my-unique-device-id")
        let myRequest = URLRequest(url: myURL!)
        webView.load(myRequest)
    }
}
```

{% endtab %}
{% endtabs %}

## Opening activations in a browser

## Open current activation in a browser

<mark style="color:blue;">`GET`</mark> `https://join.stagecast.io/?code=:code`

If you do not have an app but want people to join your activations from phone browsers you can redirect them to the **stagecast.io** homepage. There they can type in the **4-digit room code** to join your most recent active activation. In case you are redirecting them from a website and you are in possession of the room code the direct link will be **<https://join.stagecast.io/?code=:code>**

An example could be <https://join.stagecast.io/?code=0001>

#### Query Parameters

| Name | Type   | Description                                                                       |
| ---- | ------ | --------------------------------------------------------------------------------- |
| code | string | The unique 4-digits room code (not to be confused with the workspace or room id). |
| meta | string | A base64-encoded string that will be attached to the user                         |

{% tabs %}
{% tab title="200 " %}

```
...whatever webview code there is
```

{% endtab %}
{% endtabs %}

## Embed in your website

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

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

{% tabs %}
{% tab title="HTML" %}

```markup
<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.io/?code=YOUR_ROOM_CODE">
</iframe>
```

{% endtab %}

{% tab title="Example" %}

```markup
<!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.io/?code=1021">
    </iframe>
</body>
</html>
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
**Missing a feature?** This is the most high-level integration API:s that we encourage people to use. But if you have further requirements, such as needing to extract results and data out of the system, pleae feel free to contact us. We do have more API:s available - they are just not yet published here.

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**](https://forms.gle/ms6J9eHr8RKGBgjF6)\*\*\*\*
{% endhint %}

***