Javascript Library Tutorial

Javascript Library Tutorial

JavaScript Library Tutorial

  • Lets start with a simple Conference example

    Because sometimes a few lines of code worth a thousand words, here is a very simple conference example.
    If the comments are not enough you will find more explanations after ! 

  • Browser Compatibility

    Bistri Conference is compatible with WebRTC enabled browsers: Chrome 23+, Firefox 22+, Opera 18+ 

  • Prerequisites

    You must have created an application on the Bistri Developers portal in order to get your personal library keys. 

    If you don’t already have a developer account, you can freely create one at the following address:
    https://api.developers.bistri.com/signup

    HTTPS is required by the browser to access to the local stream !

  • Add the JavaScript library Client to your page

    You just have to copy the line below … 

    <script type="text/javascript" src="https://api.bistri.com/bistri.conference.min.js"></script>

    … and paste it into the body of your html page (to load it faster).

    We strongly recommend to not copy this file locally or upload it to your server. The JS library is closely linked to our api server and this file is regenerated each time a new server update is rolled out !

    Once the library is loaded the onBistriConferenceReady function is invoked. Your application code must be placed into this function to be sure that it will be properly executed at the right time.

    <script type="text/javascript">
    onBistriConferenceReady = function(){
        alert( "Bistri WebRTC Library is now ready !" );
        // here goes your application code
    }
    </script>

      You can use isCompatible() to test if the browser is WebRTC compatible

    <script type="text/javascript">
    onBistriConferenceReady = function(){
        if( bc.isCompatible() ){
            // here goes your code
        }
    }
    </script>

    Why linking the JS Library Client from Bistri’s servers instead of downloading it ?
    Each time the Library is updated a new JS client is released seamlessly. By copying it localy you may miss some important fix and encounter some issues.

      When the client library/server versions missmatch the event onClientUpdateRequired is triggered.

    bc.signaling.bind( 'onClientUpdateRequired', function(result){...} );
    • Configure Library

      Now you have to initialize the library with the personal keys you got after registering your application on the Bistri Developers Portal.
      The method init() is used initialize the library. 

      <script type="text/javascript">
      onBistriConferenceReady = function(){
          if( bc.isCompatible() ){
              bc.init( {
                  appId: "38077xxx", // application ID
                  appKey: "4f304359baa6d0fd1f9106aaebxxxxxx" // application Key
              } );
          }
      }
      </script>

        Other configuration keys are available, take a look to the Library reference

    • Open/Close a session on the server

      .connect() method is used to open the session. Event onConnected is triggered when the session is opened 

      <script type="text/javascript">
      onBistriConferenceReady = function(){
          if( bc.isCompatible() ){
              bc.init( {
                  appId: "38077xxx", // application ID
                  appKey: "4f304359baa6d0fd1f9106aaebxxxxxx" // application Key
              } );
      
              // handler for "onConnected" event
              bc.signaling.bind( "onConnected", function( data ){
                  // user is connected
              } );
              // open session
              bc.connect();
          }
      }
      </script>

      to close the session you have to call disconnect() method. Event onDisconnected is triggered when the session is closed

      // handler for "onConnected" event
      bc.signaling.bind( "onDisconnected", function( data ){
          // user is disconnected
      } );
      // close session
      bc.ondisconnected();

        When the user close the browser window/tab, bc.disconnect() method is is called

    • Get access to/Stop the local camera

      You can request an access to the local webcam by calling startStream() method.
      Once this method is invoked the browser open a popup to ask the user to give an access to the webcam. If the user accept, the callback is executed and the webcam stream objcet is passed as an argument. 

      bc.startStream( "320x240", function( stream ){ ... } );

        You can get the webcam stream in different resolution, take a look to the Library reference

      To stop the local stream you have to call stopStream() method.

      bc.stopStream( bc.getLocalStreams()[ 0 ], function( stream ){ ... } );

      When the stream has been stopped the callback is executed. The stopped stream object is passed as an argument of the callback.

    • Display/Remove a stream object into the page

      A stream object can’t be directly visualized, you need to insert it in the page using attachStream() method. According to the type of stream, a VIDEO or an AUDIO tag will be inserted. 

      bc.startStream( "640x480", function( stream ){
          // a video/audio object will be inserted into the page body
          bc.attachStream( stream, document.body );
      } );

      To remove a stream you can can invoke bc.detachStream() method.

      bc.stopStream( bc.getLocalStreams()[ 0 ], function( stream ){
          // the video/audio object will be removed from the page
          bc.detachStream( stream );
      } );
    • Join/Quit a room

      Consider a room as a “meeting point”. This is the place to join, where other users are connected.
      joinRoom() method is used to join the room, the first argument is the name of the room, the second is the max number of participants. When the user has joined the room, the event onJoinedRoom is triggered and other users already present in the room will receive an event onPeerJoinedRoom. If an error occurs an event onJoinRoomError is triggered.

      bc.signaling.bind( "onJoinedRoom", function( data ){
          // room name
          roomName = data.room;
          // room members array
          roomMembers = data.members;
      
          for( var member in roomMembers ){
              console.log( "member id: ", roomMembers[ member ].id, "member display name:", roomMembers[ member ].name );
           }
      } )
      bc.joinRoom( "myMeetingRoom", 4 );

      Note: If you try a join a room you are already in, you will get an error. The event onJoinRoomError will be triggered.

      To quit a room quitRoom() method is invoked. Once the use as quitted the room event onQuittedRoom is triggered and other users already present in the room will receive an event onPeerQuittedRoom.

      bc.signaling.bind( "onQuittedRoom", function(){
          alert( "user has quitted the room" )
      } );
      bc.quitRoom( 'myMeetingRoom' );
    • Start/End a Video Call

      Once we joined a room and retrieved the list of members we can call them using call() method. 

      // when the user receive a new stream
      bc.streams.bind( "onStreamAdded", function( stream, pid ){
      // display the stream in the body of the page
      bc.attachStream( stream, document.querySelector( "body" ) );
      } );
      
      // when the user has joined a room
      bc.signaling.bind( "onJoinedRoom", function( result ){
          var roomMembers = result.members;
          // for each user present in the room
          for( var i=0; i<roomMembers.length; i++ ){
              // we send a call request to the user
              bc.call( roomMembers[ i ].id, result.room, { stream: localStream } );
          }
      } );
      
      // the user request the server to join a room
      bc.joinRoom( "myMeetingRoom" );

      In the example above, the last user entering the room calls all the other users already present in the room.

      Once the connection is established between the peers the remote stream start to flow and event onStreamAdded is triggered on the local and remote sides

      To end a call with a particular user we use endCall() method. When the call has ended, event onStreamClosed is triggered localy and remotely.

      bc.endCall( 'dIUzMb', 'myMeetingRoom' );

      To end all the calls in a same time we use endCalls() method. When the call has ended, event onStreamClosed is triggered localy and remotely.

      bc.endCalls( 'myMeetingRoom' );