The token, and e3ds_controller.main()

A stream starts with one call, e3ds_controller.main(), and that call needs a session token. Everything else in the Web SDK sits either side of those two facts. This page is both of them: where a token comes from, and what to do with it.

The one call that starts a stream

e3ds_controller.main({
    token:      tokenResponse.token,
    socket_url: tokenResponse.socket_url,
    userName:   "your-username"
});

Both token and socket_url come back from the token API — they are two fields of one response. Anything else you pass is carried along and used where it applies.

Three ways to get a token

main() does not care where the token came from. Pick by how far along you are.

MethodGood forYour key lives
1By hand, from the Control Panel a first look, a test, a bug report — no code at all nowhere near your page
2The API, called from the browser building and developing — what the sample does in your page, readable by anyone
3The API, called from your server production on your server, where it belongs

Method 1 — by hand, from the Control Panel

No code, and no key in your page

The Control Panel makes the token for you - no JSON to write, no key in your page.

  1. Open the Control Panel's Developer Section → Token Generation tab (controlpanel.eagle3dstreaming.com/streaming-session-token-generator takes you straight there, after signing in).
  2. Pick a project - or an app and a configuration. Leave Version on Latest unless you want an older build, and choose how many minutes the token stays valid. The box below shows the request your choices build, so you can see what each one means.
  3. Press Generate token. You get the token, its socket_url, and the line to paste - press Copy code: 
e3ds_controller.main({
    token:      "the token you generated",
    socket_url: "the socket_url beside it",
    userName:   "your-username"
});

No API call, no key anywhere in your page, one line of code. This is the quickest way to prove an integration works before any of the plumbing exists.

A token is single use and expires, so the one you generated for a test is spent afterwards and harmless.

Method 2 — the API, called from the browser

What the sample does; fine while building 
POST https://token.eagle3dstreaming.com/api/v2/token/create
Content-Type: application/json
Authorization: Auth <your Streaming API key>

The body says which application to launch, for whom, and for how long:

{
  "object": {
    "core": {
      "domain":            "connector.eagle3dstreaming.com",
      "userName":          "your-username",
      "appName":           "YourAppName",
      "configurationName": "your-configuration",
      "version":           "latest"
    },
    "configurationToOverride": {}
  },
  "expiry": 60000,
  "client": "your-username"
}

object.core is the application block from sdk-config.js, passed through as-is. expiry is how long the token stays valid in milliseconds — it only has to survive long enough to start the session.

The response is what main() wants:

{
  "token":      "…",
  "socket_url": "…"
}

Method 3 — the API, called from your server

Production. The only one where your key is not published

Exactly the same request as Method 2 — same endpoint, same header, same body. The only difference is who makes it: your server instead of the browser.

Your page asks your server, your server asks Eagle 3D Streaming, and only the token comes back to the browser: 

// in your page - no key anywhere
const tokenResponse = await fetch("/api/stream-token", { method: "POST" })
                                .then(r => r.json());

Your server holds the Streaming API key and makes the call from Method 2. The browser receives a token that expires in the time you set and is single use, so a leaked one is harmless — which a leaked key never is.

It is one function's worth of change: keeping your API key off the browser.

Putting it together

// 1. Get a token — by hand, from the API, or from your own server.
const tokenResponse = await fetch("/api/stream-token", { method: "POST" })
                                .then(r => r.json());

// 2. Register your callbacks BEFORE starting. Anything assigned after
//    main() has already missed whatever fired first.
e3ds_controller.callbacks.onSessionEnding = function (message) {
    showMyEndScreen(message);
};

// 3. Start.
e3ds_controller.main({
    token:      tokenResponse.token,
    socket_url: tokenResponse.socket_url,
    userName:   "your-username"
});

Related

Last updated