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 Developer section has a Token Generation tab. Generate one, paste it into main(), and you have a stream. 

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"
});

Last updated