Contents

ShareAnywhere JS API

Quick Start

  1. Have your API_KEY to hand.

  2. Have an HTML document with at least one DOM element in it, in which you want to display the Drum ShareAnywhere Meeting Widget.

  3. Add this line to your HTML document:

    <script src="//thisisdrum.com/drum-meeting-client/js/drum-meeting-all.js"></script>
  4. Add the following to your HTML document, changing the highlighted text to contain appropriate values:

    <script>
      function quickStart(key, targetSelector, userRef, displayName, title, roomUrl, meetingUrl) {
        var displayElement = document.querySelector(targetSelector);
        var organiserRoom;
        window.DRUM.setApiKey(key)
        .then(function() {
          return window.DRUM.getOrCreateOrganiser(userRef, displayName);
        })
        .then(function(organiser) {
          organiserRoom = organiser.room;
          return window.DRUM.createMeeting(organiser, title);
        })
        .then(function(meeting) {
          var options = {
            userRef: userRef,
            displayName: displayName,
            meetingId: meeting.meetingId,
            room: organiserRoom,
            roomUrl: roomUrl,
            meetingUrl: meetingUrl
          };
          return window.DRUM.displayWidget('chair', options, displayElement);
        })
        .catch(function(error) {
          console.log('Some error occurred: ', error);
        });
      }
    </script>
    <button onclick="quickStart(
      'API_KEY',
      '#widget-target',
      'user@example.com',
      'Some User',
      'New Meeting Title',
      'http://example.com?room=<%= room %>',
      'http://example.com/meetings/<%= meetingId =>')">
    Try Me!
    </button>

    Clicking on the button will create a new organiser (or load a previously created organiser), create a new meeting, and display the new meeting in the DOM element identified by the #widget-target CSS selector.

Introduction

This document describes the ShareAnywhere JS API. It is assumed that the reader has a basic understanding of HTML and Javascript, and is familiar with the ShareAnywhere functionality. The JS API allows you to ShareAnywhere enable your web-site or web-app, integrating it into your user experience and user flows with more flexibility than the simpler ShareAnywhere HTML API. Using the JS API you will be able to control and automate the basic operations of:

  • Initialising the API with an API_KEY
  • Specify one of your users as a meeting organiser
  • Create new meetings, or fetch details for existing meetings
  • Allow a user to join a meeting as a chair, and display the ShareAnywhere meeting widget in a DOM element of your choosing
  • Allow a user to join an organiser's waiting room as a guest, and display the ShareAnywhere meeting widget in a DOM element of your choosing

These are described in more detail in the operations section.

In order to use the ShareAnywhere JS API, you will need to have signed up to ShareAnywhere, and received an API_KEY.

Operations

In the descriptions that follow, we will show how to use the ShareAnywhere JS API using form input fields to collect information to pass into the JS API, but the same principles will apply to driving the API from data retrieved from a backend service:

  • Getting Started

    You should already have your ShareAnywhere API key. You will need this so make sure you have it nearby. Before you can start to enable your web-site with ShareAnywhere, you will need to load the ShareAnywhere script into your web page, by including this in your page:

    <script src="//thisisdrum.com/drum-meeting-client/js/drum-meeting-all.js"></script>

    The ShareAnywhere JS API should now be available for you to use, via functions exposed in window.DRUM:

    • setApiKey(apiKey)
    • getOrganiser(userReference)
    • createOrganiser(userReference, displayName)
    • getOrCreateOrganiser(userReference, displayName)
    • createMeeting(organiser, meetingTitle)
    • displayWidget(role, options, element)

    Each of these functions behaves asynchronously, and returns a promise to indicate completion of the action. The promise model used is based on Kris Kowal's Q, though it is not necessary to be familiar with this, as the details of how to use the functions are described below, and in the references section.

  • Initialise the JS API

    You have to initialise the ShareAnywhere JS API with the API_KEY, using the setApiKey function. If the API_KEY is valid, the promise will succeed, and the promise's then(...) method will be invoked, otherwise the promise's catch(...) method will be invoked. So, a script fragment to initialise the JS API might look like:

    <script>
      window.DRUM.setApiKey('API_KEY')
        .then(function() {
          console.log('Success!');
        })
        .catch(function(error) {
          console.log('Failed to set API key: ', error);
        });
    </script>
  • Specifying meeting organisers

    This operation is only necessary if you want to create a new meeting.

    Creating new organisers

    Before meetings can be created, a user has to be registered as a meeting organiser. This is achieved using the createOrganiser method, which requires the user reference (we suggest the user's email address), and their display name:

    <script>
      window.DRUM.createOrganiser('valen@b4.com', 'Jeffrey Sinclair')
        .then(function(organiser) {
          console.log('Successfully created an organiser! Their room is: ', organiser.room);
        })
        .catch(function(error) {
          console.log('Failed to create an organiser: ', error);
        });
    </script>

    You can then use the organiser object passed into the then handler to create new meetings for that organiser.

    Please note: Creating an organiser will create an additional subscription. Depending on the plan you have purchased there may be an additional charge to the service we provide you. Please see organiser subscriptions for more details.

    Using previously created organisers

    If you have previously created the organiser, you will still need to retrieve the organiser object for them, in order to create new meetings. This is achieved using the createOrganiser method, which requires the user reference used to create the organiser:

    <script>
      window.DRUM.getOrganiser('valen@b4.com')
        .then(function(organiser) {
          console.log('Successfully fetched an organiser! Their room is: ', organiser.room);
        })
        .catch(function(error) {
          console.log('Failed to fetch an organiser: ', error);
        });
    </script>

    As with the createOrganiser method, you can use the organiser object passed into the then handler to create new meetings for that organiser.

    Not sure if the organiser was created?

    As a convenience, the JS API exposes a getOrCreateOrganiser method, which will attempt to retrieve an organiser from their user reference, and if that fails it will proceed to attempt to create an organiser:

    <script>
      window.DRUM.getOrCreateOrganiser('valen@b4.com', 'Jeffrey Sinclair')
        .then(function(organiser) {
          console.log('Successfully fetched or created an organiser! Their room is: ', organiser.room);
        })
        .catch(function(error) {
          console.log('Failed to fetch or create an organiser: ', error);
        });
    </script>

    As with the previous methods, you can use the organiser object passed into the then handler to create new meetings for that organiser.

  • Create a new meeting

    Having created / retrieved an organiser, and having the organiser object from doing so, it is now possible to create a new meeting using the createMeeting method as follows:

    <script>
      window.DRUM.getOrCreateOrganiser('valen@b4.com', 'Jeffrey Sinclair')
        .then(function(organiser) {
          return window.DRUM.createMeeting(organiser, 'Hello old friends');
        })
       .then(function(meeting) {
          console.log('Success! Created new meeting, with id: ', meeting.meetingId);
        })
        .catch(function(error) {
          console.log('Error: ', error);
        });
    </script>
  • Join a meeting as a chair

    Having created a meeting, it is now possible to join the meeting as a meeting chair, using the displayWidget method, at which point the ShareAnywhere Meeting widget will be displayed in the specified DOM element.

    When joining a meeting as a chair, it is also necessary to supply the following data in the options parameter:

    • user reference for the chair (may or may not be the same as the organiser)
    • display name for the chair
    • meeting id for the meeting, which for a new meeting is the id field of the object passed to createMeeting's then handler
    • room for the meeting, which is the room field of the organiser object. For now, the room is also the same as the organiser's user reference, but this may change longer term.
    • room URL (See: room URL)
    • meeting URL (See: meeting URL)

    See displayWidget for list of all available options.


    The following script extract illustrates this:

    <script>
      var organiserRoom;
      window.DRUM.getOrCreateOrganiser('valen@b4.com', 'Jeffrey Sinclair')
        .then(function(organiser) {
          organiserRoom = organiser.room;
          return window.DRUM.createMeeting(organiser, 'Hello old friends');
        })
        .then(function(meeting) {
          console.log('Success! Created new meeting, with id: ', meeting.meetingId);
          var displayElement = document.querySelector('#widget-target');
          var options = {
            userRef: 'garibaldi@b5.com',
            displayName: 'Michael Garibaldi',
            meetingId: meeting.meetingId,
            room: organiserRoom,
            roomUrl: 'http://example.com?room=<%= room %>',
            meetingUrl: 'http://example.com/meetings/<%= meetingId =>'
          };
          return window.DRUM.displayWidget('chair', options, displayElement);
        })
        .then(function() {
          console.log('Success! Displayed meeting!');
        })
        .catch(function(error) {
          console.log('Error: ', error);
        });
    </script>
  • Join a waiting room as a guest

    It is also possible to join an organiser's waiting room as a guest, using the displayWidget method, at which point the ShareAnywhere Meeting widget will be displayed in the specified DOM element.

    When joining a meeting as a guest, it is also necessary to supply the following data in the options parameter:

    • user reference for the guest (may or may not be the same as the organiser)
    • display name for the guest
    • room for the meeting, which is the room field of the organiser object. For now, the room is also the same as the organiser's user reference, but this may change longer term.
    • room URL (See: room URL)

    See displayWidget for list of all available options.


    The following script extract illustrates this:

    <script>
      var organiserRoom;
      window.DRUM.getOrCreateOrganiser('valen@b4.com', 'Jeffrey Sinclair')
        .then(function(organiser) {
          organiserRoom = organiser.room;
          return window.DRUM.createMeeting(organiser, 'Hello old friends');
        })
        .then(function(meeting) {
          console.log('Success! Created new meeting, with id: ', meeting.meetingId);
          var displayElement = document.querySelector('#widget-target');
          var options = {
            userRef: 'londo@b5.com',
            displayName: 'Londo Mollari',
            room: organiserRoom,
            roomUrl: 'http://example.com?room=<%= room %>'
          };
          return window.DRUM.displayWidget('guest', options, displayElement);
        })
        .then(function() {
          console.log('Success! Displayed waiting room!');
        })
        .catch(function(error) {
          console.log('Error: ', error);
        });
    </script>
  • Listening for the exit event

    Once the user has joined the meeting or waiting room its a good idea to listen for the exit event.

    This event fires when the user presses the leave button, is evicted from a meeting or waiting room, loses their connection to the meeting, or when the meeting ends.


    The following script extract illustrates this:

    <script>
      window.DRUM.on('exit', function(event) {
        console.log('You have exited the', event.view, 'reason for exit:', event.reason);
        // Show a custom exit view/page
      });
    </script>

Reference

Terms and concepts

  • API_KEY

    The API_KEY is used both to identify and authenticate your use of the ShareAnywhere API.

  • Chair Role

    The meeting chair is one of the two main roles that ShareAnywhere Meeting participants can have. Meeting chairs are allowed to join meetings directly without having to join via the organiser's waiting room. They have full access to all the ShareAnywhere Meeting widget functionality: they can start and stop meetings, add and present files, add guests waiting in the organiser's waiting room into a started meeting, they can promote and demote guests to be guest presenters, and they can evict participants. Typically the meeting organiser is also the meeting chair, but this is not enforced. Equally, typically meetings will only have one chair, but more are allowed.

  • Guest Role

    A meeting guest is one of the two main roles that ShareAnywhere participants can have. Meeting guests may not join a meeting directly, and are placed into an organiser's waiting room when they join, from where a meeting chair can add them into a started meeting. Guests are not able to upload files, or control aspects of the ShareAnywhere Meeting widget. Guests may be promoted to guest presenters by a chair, at which point they can add and present files.

  • Meeting URL

    If the parent web-site supports it, this is a URL which will resolve to a specific previously created meeting, and can be used by chairs to join meetings.

  • Organiser Subscriptions

    One subscription provides you with one meeting host/organiser. Depending on your plan, you will have a set limit of meeting attendees who can join a meeting at any given time. Only one meeting can be held simultaneously per subscription. However, this does not limit the quantity of meetings you can create. There is no set limit to the quantity of subscriptions for each business. Please contact the sales team if you require additional subscriptions. We will not charge you for additional subscriptions without your authorisation.

  • Room URL

    If the parent web-site supports it, this is a URL which will resolve to an organiser's waiting room, and can be used by guests to join the waiting room.

  • User References

    ShareAnywhere delegates all user management to the parent web-site / web-app, however it needs to have some unique reference to a user so that it can identify and differentiate between them. This unique reference is called the User Reference, or userRef for short. Ideally it should be the email address of the user, but other values are permissible.

  • Waiting Room

    An organiser's waiting room is where guests first arrive, and wait before being admitted to a specific meeting. Chairs in the meeting can see which guests are in the waiting room, and choose to add them to the meeting, leave them in the waiting room till later, or evict them.

JS API methods

These are exposed in the window.DRUM object.

  • createMeeting(organiser, title)

    Use this method to create a new meeting for an organiser.

    Parameters
    Returns

    A promise. Success results in the then handler being called with a meeting object. The meeting object contains a number of fields, but for the purposes of the JS API, the only one that is useful is the id field, which is used in the options to displayWidget when allowing a chair to join a meeting. Failure results in the catch handler being called, with an error object describing the reason for the failure.

  • createOrganiser(userReference, displayName)

    Use this method to create a new organiser. If the organiser has previously been created, this will result in a failure.

    Parameters
    • userReference
      A unique string which identifies the user. We suggest using the user's email address.
    • displayName
      The user's name, used as a friendlier alternative to an email address or other user reference.
    Returns

    A promise. Success results in the then handler being called with an organiser object. The organiser object contains a number of fields, but for the purposes of the JS API, the only one that is useful is the room field, which is used in the options to displayWidget when allowing a guest to join a waiting room. Failure results in the catch handler being called, with an error object describing the reason for the failure.

  • displayWidget(role, options, element)

    Use this method to display the meeting widget in a DOM element, specifying user and the role.

    Parameters
    • role
      A string identifying the role. Permissible roles are chair, or guest. If joining as a chair, the id of the meeting must be passed in the options. If joining as a guest, the room of the meeting organiser myst be passed in the options.
    • options

      An object containing a number of fields, depending on whether the role is chair or guest.

      For chair, the options object looks like this:

      {
        userRef: 'chair@example.com',
        displayName: 'Chair name',
        meetingId: meeting.meetingId, // taken from the meeting object returned from createMeeting
        room: organiser.room, // taken from the organiser object returned from create / get / getOrCreate Organiser
        roomUrl: 'http://example.com/', // a URL / route to your portal which includes the the organiser's room
        meetingUrl: 'http://example.com/', // a URL / route to your portal which includes the meeting ID.
        allowVideo: false // Enable or disable video calls in the meeting. (Optional)
        allowLockMeeting: true, // If true the chair can lock/unlock the meeting. (Optional)
        allowStopMeeting: true, // If true the chair can stop the meeting, if false the meeting will stop when the last chair leaves. (Optional)
        allowScreenShare: true, // Enable or disable screen sharing in the meeting. (Optional)
        showGuestPin: true, // When role is chair, show or hide guest pin. (Optional)
        colors: {} // Add colorParams for custom colors. (Optional)
      }

      For guest, the options object looks like this:

      {
        userRef: 'guest@example.com',
        displayName: 'Guest name',
        room: organiser.room, // taken from the organiser object returned from create / get / getOrCreate Organiser
        roomUrl: 'http://example.com/', // a URL / route to your portal which includes the the organiser's room
        allowVideo: false, // Enable or disable video calls in the meeting. (Optional)
        allowScreenShare: true, // Enable or disable screen sharing in the meeting. (Optional)
        colors: {} // Add colorParams for custom colors. (Optional)
      }
      colorParams

      Up to 4 colors can be specified. They may be specified in any order. At runtime, these colors will be used to replace the default color scheme. The expected color arguments are as follows:

        base,
        danger,
        success,
        warning
                                  

      e.g. { base: '#6b7cba', warning: 'yellow' } would produce a meeting with a blue header and yellow warnings. All other elements will use the default color scheme.

    • element
      The DOM element into which to insert the markup for the Meeting Widget. It is NOT sufficient to pass in a CSS selector for this. It must be an element object as returned by document.querySelector, document.getElementById, etc.
    Returns

    A promise. Success results in the then handler being called with no arguments. Failure results in the catch handler being called, with an error object describing the reason for the failure.

  • getOrCreateOrganiser(userReference, displayName)

    Use this method to fetch an existing organiser, or create a new one.

    Parameters
    • userReference
      A string. The user reference of the organiser to try to retrieve. If no organiser with that user reference is found then a new organiser is created with this user reference and the specified display name.
    • displayName
      This display name to use if it is necessary to create a new organiser.
    Returns

    A promise. Success results in the then handler being called with an organiser object. The organiser object contains a number of fields, but for the purposes of the JS API, the only one that is useful is the room field, which is used in the options to displayWidget when allowing a guest to join a waiting room. Failure results in the catch handler being called, with an error object describing the reason for the failure.

  • getOrganiser(userReference)

    Use this method to fetch a previously created organiser from their user reference.

    Parameters
    • userReference
      A string. The user reference of the organiser to try to retrieve. If no organiser with that user reference is found, then the call fails.
    Returns

    A promise. Success results in the then handler being called with an organiser object. The organiser object contains a number of fields, but for the purposes of the JS API, the only one that is useful is the room field, which is used in the options to displayWidget when allowing a guest to join a waiting room. Failure results in the catch handler being called, with an error object describing the reason for the failure.

  • setApiKey(API_KEY)

    Use this method to initialise the ShareAnywhere JS API with an API_KEY. This method may only be called once, otherwise it will return a failure. If an invalid API_KEY is specified, that will also generate a failure. Until the JS API has been initialised with a valid API_KEY, all other API methods will fail.

    Parameters
    • apiKey
      A string. This is the API_KEY you should have been given when you signed up with ShareAnywhere.
    Returns

    A promise. Success results in the then handler being called with no parameters. The JS API is now initialised. Failure result in the catch handler being called, with an error object describing the reason for the failure.

Events


Adding and Removing Event Listeners

Use the following to add/remove event listeners:

  function onExit(event) {
    console.log('You have exited the meeting.');
  }

  // Add an event listener
  window.DRUM.on('exit', onExit);

  // Remove an event listener
  window.DRUM.off('exit', onExit);      

List of ShareAnywhere Events

  • exit

    Fired when a user exits a meeting.

    Event Properties
    • reason
      • 'stop' - The meeting has been ended.
      • 'left' - The user left the meeting.
      • 'evicted' - The user has been evicted from the meeting.
      • 'connection error' - The user has lost their connection to the meeting.
    • view
      • 'meeting' - The user was viewing the meeting when the exit event occurred.
      • 'waiting room' - The user was viewing the waiting room when the exit event occurred.
    • data

      An object containing the meetingId if viewing the meeting or the organiserRef if viewing the waiting room.

Examples

The following are some form-driven examples of using the JavaScript API. The reader is invited to use these interactively, by modifying a copy of this document.

Settings

Organiser Information

Meeting Details

Join / Display Information

Meeting Widget

Use the forms above to create a meeting and display the meeting widget.