Embedding the Widget

This is legacy documentation. We are no longer onboarding new Gruveo for Developers customers.

Important: A Gruveo widget must be embedded in an HTTPS page of your site. Due to security restrictions in certain browsers (e.g. Chrome), the embed WILL NOT work if inserted in a non-secure HTTP page.

The following code will insert a responsive Gruveo embed on the page with the pre-populated "orange67" room name:

<html>
<body>
  <!-- The embed's <iframe> will replace this <div> tag. -->
  <div id="myembed"></div>

  <script>
    var clientId = "demo";

    // This code loads the Gruveo Embed API code asynchronously.
    var tag = document.createElement("script");
    tag.src = "https://www.gruveo.com/embed-api/";
    var firstScriptTag = document.getElementsByTagName("script")[0];
    firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

    // This function gets called after the API code downloads. It creates
    // the actual Gruveo embed and passes parameters to it.
    var embed;
    function onGruveoEmbedAPIReady() {
      embed = new Gruveo.Embed("myembed", {
        responsive: 1,
        embedParams: {
          clientid: clientId,
          code: "orange67"
        }
      });

      embed
        .on("error", onEmbedError)
        .on("requestToSignApiAuthToken", onEmbedRequestToSignApiAuthToken);
    }

    function onEmbedError(e) {
      console.error("Received error " + e.error + ".");
    }

    function onEmbedRequestToSignApiAuthToken(e) {
      // The below assumes that you have a server-side signer endpoint at /signer,
      // where you pass e.token in the body of a POST request.
      fetch('/signer', {
        method: 'POST',
        body: e.token
      })
        .then(function(res) {
          if (res.status !== 200) {  
            return;  
          }
          res.text()
            .then(function(signature) {
              embed.authorize(signature);
            });
        });
    }
  </script>
</body>
</html>

<html>

<body>

var clientId = "demo";

// This code loads the Gruveo Embed API code asynchronously.

var tag = document.createElement("script");

tag.src = "https://www.gruveo.com/embed-api/";

var firstScriptTag = document.getElementsByTagName("script")[0];

firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

// This function gets called after the API code downloads. It creates

// the actual Gruveo embed and passes parameters to it.

var embed;

function onGruveoEmbedAPIReady() {

embed = new Gruveo.Embed("myembed", {

responsive: 1,

embedParams: {

clientid: clientId,

code: "orange67"

}

});

embed

.on("error", onEmbedError)

.on("requestToSignApiAuthToken", onEmbedRequestToSignApiAuthToken);

}

function onEmbedError(e) {

console.error("Received error " + e.error + ".");

}

function onEmbedRequestToSignApiAuthToken(e) {

// The below assumes that you have a server-side signer endpoint at /signer,

// where you pass e.token in the body of a POST request.

fetch('/signer', {

method: 'POST',

body: e.token

})

.then(function(res) {

if (res.status !== 200) {

return;

}

res.text()

.then(function(signature) {

embed.authorize(signature);

});

}

</script>

</body>

</html>

The code above will render the following embed:

Let's break down this example. After the API’s JavaScript code loads, the onGruveoEmbedAPIReady function is called, at which point you can construct the Gruveo.Embed object to insert an embed in your page. (Note that you must implement the onGruveoEmbedAPIReady function for the embedding to work.)

The following parameters are specified by the embed constructor:

The first parameter specifies the id of the DOM element that the embed <iframe> tag will replace.
The second parameter specifies embed options. The following properties are used:
- width (number) – The width of the embed. The default value is 640. Ignored if the responsive property is supplied.
- height (number) – The height of the embed. The default value is 440. Ignored if the responsive property is supplied.
- responsive (0 or 1) – Whether to enable the responsive sizing mode of the embed. The default value is 0. Enabling the responsive mode makes the embed ignore the width and height properties.
- embedParams (object) – Any extra embed parameters that can be used to customize the embed.

Authentication

To use the Gruveo widget, you need to pass the clientid embed parameter containing your client ID. You can obtain your client ID and API secret on this page. For development purposes, you can also use the following demo credentials which limit all calls to 5 minutes:

Client ID: demo
API secret: W62wB9JjW3tFyUMtF5QhRSbk

Token Signing

Client Side

The Gruveo embed fires the requestToSignApiAuthToken event every time a video or voice call is initiated. For the calls to successfully connect, you will need to implement a handler for the requestToSignApiAuthToken event, where you:

Pass the received event.token value to your server-side signer endpoint
Receive the Base64-encoded HMAC signature for the token from the server side
Pass the signature to the Gruveo API using the embed.authorize() method.

The token HMAC is computed with SHA-256 as the hash function and with your API secret as the HMAC's secret key. To avoid exposing your API secret in client code, we strongly recommend computing the HMAC signature on the server side. Please see below for some code examples.

Server Side

Here is how you can compute the HMAC on the server side in a Node.js app (example taken from the server-side part of our Embed API demo). This snippet assumes that the token to sign arrives to the server in the req parameter, i.e. the HTTP request body:

const secret = 'MY_API_SECRET';

//...

app.all('/signer', cors(corsOptions), function (req, res) {
  req
    .pipe(crypto.createHmac('sha256', secret))
    .pipe(base64.encode())
    .pipe(res.set('Content-Type', 'text/plain'));
});

const secret = 'MY_API_SECRET';

//...

app.all('/signer', cors(corsOptions), function (req, res) {

req

.pipe(crypto.createHmac('sha256', secret))

.pipe(base64.encode())

.pipe(res.set('Content-Type', 'text/plain'));

});

Here is an equivalent PHP snippet, which again assumes that the token arrives in the HTTP request body:

<?php
  $secret = 'MY_API_SECRET';
  $hmac = hash_hmac('sha256', file_get_contents('php://input'), $secret, TRUE);
  $hmac = base64_encode($hmac);
  echo($hmac);
?>

<?php

$secret = 'MY_API_SECRET';

$hmac = hash_hmac('sha256', file_get_contents('php://input'), $secret, TRUE);

$hmac = base64_encode($hmac);

echo($hmac);

Security Considerations

You should keep your API secret secure at all times and never expose it in the client code. We strongly recommend computing the token HMAC on the server side with proper authentication of your web application. Please refer to our Embed API demo for a basic example of computing the HMAC on the server side.