Gruveo Embed API Reference

The Embed API lets you add a Gruveo embed to your page and control the embed using JavaScript. Using the functions exposed by the API, you can make the embed perform certain functions, e.g. start a call or end it. You can also add event listeners that will get triggered in response to certain embed events, such as a state change.

The purpose of this guide is to explain how to use the API. It details the types of the events that the API can send and information supplied by these events. It also lists the JavaScript functions that you can call to control the Gruveo embed as well as the parameters that you pass to those functions.

Requirements

Gruveo must be embedded in an HTTPS page of your site. The embed WILL NOT work if inserted in a non-secure HTTP page. (Why?)

The Embed API relies on the user’s browser supporting the HTML5 postMessage feature. postMessage is supported by most modern browsers.

Any page that uses the Embed API must implement the onGruveoEmbedAPIReady JavaScript function. This function gets called after the page has finished downloading the JavaScript for the Embed API, which enables you to then use the API on your page. This function is where you typically use the API, e.g. create any embed objects to display.

A Simple Example

The sample PHP page below creates a Gruveo embed that will start a video call on the “mycode123” code immediately upon loading. The embed will end the call 10 seconds after it is established.

Please see below for the explanations for the numbered comments in the code.

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

  <script>
    // 2. 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);

    // 3. This function gets called after the API code downloads. It creates
    //    the actual Gruveo embed (the <iframe>) and wires up the event
    //    handlers.
    var embed;
    function onGruveoEmbedAPIReady() {
      <?php
        $clientid = 'YOUR_CLIENT_ID';
        $secret = 'YOUR_API_SECRET';
        $generated = time();
        $signature = base64_encode(hash_hmac('sha256', (string)$generated, $secret, TRUE));
      ?>
      embed = new Gruveo.Embed("myembed", {
        width: 680,
        height: 465,
        embedParams: {
          clientid: "<?php print $clientid; ?>",
          generated: <?php print $generated; ?>,
          signature: "<?php print $signature; ?>",
          color: "63b2de"
        }
      });

      embed
        .on("ready", onEmbedReady)
        .on("stateChange", onEmbedStateChange);
    }

    // 4. This function will get called by the API when the embed is ready.
    function onEmbedReady(e) {
      embed.call("mycode123", true);
    }

    // 5. The API will call this function when the embed's state changes.
    //    The function indicates that after a call is established
    //    (state == "call"), the embed should hang up after 10 seconds.
    function onEmbedStateChange(e) {
      if (e.state == "call") {
        setTimeout(endCall, 10000);
      }
    }
    function endCall() {
      embed.end();
    }
  </script>
</body>
</html>

Here is a step-by-step explanation of the above code:

  1. The purpose of the <div> tag is to specify where the embed’s <iframe> needs to be placed. The constructor of the embed object identifies the <div> by its id and replaces it with the embed <iframe>.
  2. The Embed API JavaScript code is loaded by injecting a <script> tag into the page’s DOM. This approach ensures that the code is downloaded asynchronously.
  3. The onGruveoEmbedAPIReady function will get executed as soon as the Embed API code gets downloaded. The sample implementation defines a global embed variable that refers to the particular embed instance and then constructs the actual embed object. (Please see the Loading an Embed section below for details on the clientid, generated and signature parameters passed to the constructor.)
    Finally, the embed object’s on method is used to bind handler functions to the embed’s ready and stateChange events.
  4. The onEmbedReady function is bound to the embed’s ready event and so it will be called whenever the embed’s ready event fires. This particular event is fired when the Gruveo embed is loaded and is ready for operation.
  5. The onEmbedStateChange function will be called whenever the embed’s state changes, which may indicate that a call has been initialized, a “no WebRTC” message is displayed and so forth. The function indicates that after a call has been established (i.e. embed state switches to call), it will be set to end after 10 seconds.

Loading an Embed

After the API’s JavaScript code loads, the onGruveoEmbedAPIReady function will get called, at which point you can construct the Gruveo.Embed object to insert an embed in your page. Here is an excerpt from the onGruveoEmbedAPIReady implementation in the example above:

<?php
  $clientid = 'YOUR_CLIENT_ID';
  $secret = 'YOUR_API_SECRET';
  $generated = time();
  $signature = base64_encode(hash_hmac('sha256', (string)$generated, $secret, TRUE));
?>
embed = new Gruveo.Embed("myembed", {
  width: 680,
  height: 465,
  embedParams: {
    clientid: "<?php print $clientid; ?>",
    generated: <?php print $generated; ?>,
    signature: "<?php print $signature; ?>",
    color: "63b2de"
  }
});

The following parameters are specified by the embed constructor:

  1. The first parameter specifies the id of the DOM element that the embed <iframe> tag will replace.
  2. The second parameter specifies embed options. The following properties are used:
    • width (number) – The width of the embed. The default value is 640.
    • height (number) – The height of the embed. The default value is 440.
    • embedParams (object) – The embed parameters that can be used to customize the embed. Valid clientid, generated and signature parameters are required for any “extended” parameters to take effect, including an automatically passed parameter that enables the embed to be controlled by the JavaScript API.

The clientid, generated and signature values passed in embedParams are designed to prevent unauthorized access to the embed API as well as unauthorized usage of extended embed parameters.

  • The clientid parameter is your unique Gruveo API client identifier.
  • The generated parameter must contain the UNIX timestamp of when the embed was generated.
  • The signature parameter must contain a Base64-encoded SHA-256 HMAC of the generated timestamp with your API secret as the key.

Click here to apply for the Gruveo Embed API Beta Program and get your client ID and API secret.

The embed <iframe> checks the validity of the clientid, generated and signature parameters and ignores any extended parameters passed in embedParams if the check fails. This also means that the embed will not respond to the host page’s JavaScript API requests.

Functions

After you have constructed a Gruveo.Embed object, you can call its methods to control the various aspects of the embed. This section describes the currently available methods.

Call Controls

embed.call(code:String, video:Boolean):Gruveo.Embed
Starts a call on code. The video parameter specifies a video call if true and a voice one if false.
embed.end():Gruveo.Embed
Ends the current call.
embed.toggleVideo(video:Boolean):Gruveo.Embed
Sets the state of the camera. Pass true in the video parameter to turn the camera on; pass false to turn it off.
embed.toggleAudio(audio:Boolean):Gruveo.Embed
Sets the state of the microphone. Pass true in the audio parameter to unmute the mic or pass false to mute it.

Call State

embed.getState():String
Returns the current state of the embed.

Adding Event Handlers

on(event:String, handler:Function):Gruveo.Embed
Adds a handler function to the specified event. handler is a reference to the function that should get called when the specified event fires. See the Events section below for a description of the different events that the embed might fire.

Method Chaining

Every method of the embed object, except for getters (i.e. methods whose name starts with get) returns the embed object itself. This makes it possible to “chain” API method calls:

embed.on("stateChange", onStateChange).call("test", false);

Events

The API fires events to notify the host application about any changes to the embed. You can subscribe to events with the help of the on method of the Gruveo.Embed object.

Each event handler is passed a sole event object whose properties may contain additional information about the event. For example, the event object passed by the stateChange event has the state property that contains the new embed state.

Here is a list of the events fired by the API:

ready
This event is fired whenever the embed has finished loading and is ready to interact with the API. Your application should implement a handler for the ready event if you wish to perform certain actions (e.g. start a call) as soon as the embed is ready.
stateChange
This event fires whenever the embed’s state changes. The new state is specified in the state property of the event object passed to the event handler. Depending on state, the event object may contain additional properties specific to that embed state.
Possible values of the state property are:

  • ready (idle). Provides the following additional properties in the event object:
    • callDuration – Duration of the last call in seconds.
  • no-webrtc (displaying a “no WebRTC support” message)
  • plugin-needed (displaying a WebRTC plugin installation prompt)
  • permissions-request (prompting the user for camera/microphone permissions)
  • call-setup (waiting for the other party to join)
  • call (call in progress)
streamStateChange
This event is fired whenever the state of the embed’s media stream changes, i.e. the camera or the microphone gets muted or unmuted. The video property of the event object passed to the event handler specifies the state of the camera (true for on and false for off). The state of the microphone is likewise specified in the audio property of the event object.
callInit
This event fires whenever a call is initialized.
busy
Fires whenever a call code is busy.
hangup
This event is fired whenever a call as ended as a result of the user or API action (as opposed to, e.g. remote party disconnecting or lost connection).

Revision History

July 21, 2016

  • The new clientid parameter has been added to the API signing schema.

April 19, 2016

  • The new callInit, busy and hangup API events have been added to allow for better tracking of user interaction with the Gruveo embed.

February 24, 2016

  • The new toggleVideo() and toggleAudio() API methods allow for muting or unmuting the camera and the microphone, respectively.
  • The new streamStateChange event is fired whenever the camera and/or the microphone gets muted or unmuted.

December 22, 2015

  • The Requirements section has been updated to note that Gruveo will not work if embedded in a non-secure HTTP page.

October 19, 2015

  • Initial version.