SoundProofJS 0.1.3

Welcome to the SoundProof JavaScript library documentation!


Version History (Change log)


Overview

Here are some general guidelines on how to import and use the SoundProof JS library.

The instructions assume that your website (on which you wish to deploy SoundProof for authentication) is at https://your.domain.com.

  1. In order to use SoundProof in your page you need to first download the following files:

    • https://xxxxxx.futurae.com/assets/js/soundproof/soundproof.min.js
    • https://xxxxxx.futurae.com/assets/js/soundproof/WebAudioRecorderOgg.min.js
    • https://xxxxxx.futurae.com/assets/js/soundproof/OggVorbisEncoder.min.js

    where "xxxxxx.futurae.com" is your Service hostname. Then, place these files under a common path under which they will be served by your server, for example:

    • https://your.domain.com/assets/js/soundproof/

    Then, import soundproof.min.js in the page where SoundProof will be executed:

    <script src="https://your.domain.com/assets/js/soundproof/soundproof.min.js"></script>

    If the file is imported successfully, then the soundproof namespace which includes all relevant functionality will become available to the page. Note that you must not explicitly import the rest of the js files in your page using a <script> tag. They will be fetched and loaded automatically by soundproof.min.js.

  2. Initialise the SoundProof object at page load, supplying the various callback functions in order to track various events during the authentication. Here is an example on how to do it:

      var SoundProofFactor = function() {
        var self = this;
    
        self.audioInitSuccess = function() {
          console.log('Audio init success');
        };
    
        self.complete = function() {
          console.log('SoundProof completed');
        };
    
        self.deviceTimeout = function(msg) {
          console.log('Device notification timeout: ', msg);
        };
    
        self.error = function(err, msg) {
          // Check the type of err in order to determine the kind of error 
          // and prompt the user accordingly, if necessary
          console.log('SoundProof error: ', err, msg);
        };
    
        self.newDeviceMustApprove = function(msg) {
          console.log('New browser, the user must approve the login on their device: ', msg);
        };
    
        self.recordingStart = function() {
          console.log('Recording started');
        };
    
        self.recordingTooSilent = function(msg) {
          console.log('Recording too silent, please make some noise');
        };
    
        self.recordingEnd = function() {
          console.log('Recording ended');
        };
    
        self.soundProofFailed = function(msg) {
          // This callback indicates that SoundProof failed but we are in "approve_combo" mode, 
          // and the session has not finished yet, as the user may still manually approve the login
          console.log('SoundProof failed notification (user can still approve): ', msg);
        };
    
        self.timeout = function() {
          console.log('SoundProof timeout');
        };
    
        self.soundproof = new soundproof.SoundProof({
          callback: {
            onAudioInitSuccess: self.audioInitSuccess,
            onComplete: self.complete,
            onDeviceTimeout: self.deviceTimeout,
            onError: self.error,
            onNewDeviceMustApprove: self.newDeviceMustApprove,
            onRecordingStart: self.recordingStart,
            onRecordingTooSilent: self.recordingTooSilent,
            onRecordingEnd: self.recordingEnd,
            onSoundProofFailed: self.soundProofFailed,
            onTimeout: self.timeout
          }
        });
      };
    
      var spFactor = new SoundProofFactor();
    
      // check if SoundProof is supported in this browser
      spFactor.soundproof.checkSupport(function(result) {
            console.log('SoundProof check support result: ', result);
      });
  3. Start the SoundProof authentication step by providing the session_token that your backend server retrieved by calling /srv/auth/v1/user/auth. This can be achieved with a variety of ways. For example, you can:

    • use XHR or WebSocket, or
    • place the session_token somewhere in the DOM and make it available in JavaScript

      Once the session_token is available you can call:

      spFactor.soundproof.start(session_token);
  4. When SoundProof has been completed, you have to call /srv/auth/v1/user/auth_status (see the Auth API Reference) to get the final result of the authentication step (NOTE: the result of the authentication can only be retrieved by the backend API and not via the SoundProof JS library).

    By implementing the SoundProof callbacks you can respond to any kind of event, e.g. onComplete(), onError(). In order to retrieve the authentication step status, you can:

    • wait for SP onComplete() callbacks to be called and then make an XHR (or WebSocket send) to your backend server, which in turn makes the call to /srv/auth/v1/user/auth_status. The latter will respond with a final status (allow, deny) immediately, since SP has already been completed
    • make an XHR (or WebSocket send) to your backend server, which in turn makes a synchronous call to /srv/auth/v1/user/auth_status with final_result=true right after starting SP and wait for the response (using a deferred object or promise)