Zero-Touch (SoundProof) JS SDK

Current Version: 0.3.1 (Change log)

Quick Start Guide

This guide will show you how to import and use the SoundProof JS SDK in four easy steps.

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

Step 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.

Step 2

Initialize the SoundProof object at page load, supplying the various callback functions in order to track various events during the authentication. You can also configure the base URL (which should be the Service hostname) as well as other optional parameters (see here for details). Here is an example on how to do it:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77

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({
    baseURL: 'https://xxxxxx.futurae.com', // default baseURL value: 'https://api.futurae.com'
    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;

// check if SoundProof is supported in this browser
soundproof.SoundProof.checkSupport(function(result) {
      console.log('SoundProof check support result: ', result);
      if (result) {
        spFactor = new SoundProofFactor();
      } else {
        // Use another method, such as One-Touch
        // using the Auth API in the backend
        // ...
      }
});

Step 3

Start the SoundProof authentication step by providing the session_token that your backend server retrieved by calling Auth API’s /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);

Step 4

When SoundProof has been completed, you have to call Auth API’s /user/auth_status to get the final result of the authentication step

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() callback to be called and then make an XHR (or WebSocket send) to your backend server, which in turn makes the call to /user/auth_status. The latter will respond with a final status (allow, deny) once the final result is available.
• make an XHR (or WebSocket send) to your backend server, which in turn makes a synchronous call to /user/auth_status with final_result=true right after starting SP and wait for the response (using a deferred object or promise)