Fire an optional JitsiMediaDevices.PERMISSION_PROMPT_IS_SHOWN event when browser shows user media permission prompt when calling createLocalTracks

JitsiMediaDevices.js

@@ -88,6 +88,13 @@ var JitsiMediaDevices = {
      */
     removeEventListener: function (event, handler) {
         eventEmitter.removeListener(event, handler);
+    },
+    /**
+     * Emits an event.
+     * @param {string} event - event name
+     */
+    emitEvent: function (event) {
+        eventEmitter.emit.apply(eventEmitter, arguments);
     }
 };
 

JitsiMediaDevicesEvents.js

@@ -11,7 +11,17 @@ var JitsiMediaDevicesEvents = {
      *  MediaDeviceInfo-like objects that are currently connected.
      *  @see https://developer.mozilla.org/en-US/docs/Web/API/MediaDeviceInfo
      */
-    DEVICE_LIST_CHANGED: "mediaDevices.devicechange"
+    DEVICE_LIST_CHANGED: "mediaDevices.devicechange",
+    /**
+     * Indicates that the environment is currently showing permission prompt to
+     * access camera and/or microphone. The event provides the following
+     * parameters to its listeners:
+     *
+     * @param {'chrome'|'opera'|'firefox'|'iexplorer'|'safari'|'nwjs'
+     *      |'react-native'|'android'} environmentType - type of browser or
+     *      other execution environment.
+     */
+    PERMISSION_PROMPT_IS_SHOWN: "mediaDevices.permissionPromptIsShown"
 };
 
 module.exports = JitsiMediaDevicesEvents;

JitsiMeetJS.js

@@ -18,6 +18,11 @@ var Statistics = require("./modules/statistics/statistics");
 var Resolutions = require("./service/RTC/Resolutions");
 var ScriptUtil = require("./modules/util/ScriptUtil");
 var GlobalOnErrorHandler = require("./modules/util/GlobalOnErrorHandler");
+var RTCBrowserType = require("./modules/RTC/RTCBrowserType");
+
+// The amount of time to wait until firing
+// JitsiMediaDevicesEvents.PERMISSION_PROMPT_IS_SHOWN event
+var USER_MEDIA_PERMISSION_PROMPT_TIMEOUT = 500;
 
 function getLowerResolution(resolution) {
     if(!Resolutions[resolution])
@@ -99,13 +104,36 @@ var LibJitsiMeet = {
      * will be returned trough the Promise, otherwise JitsiTrack objects will be returned.
      * @param {string} options.cameraDeviceId
      * @param {string} options.micDeviceId
+     * @param {boolean} (firePermissionPromptIsShownEvent) - if event
+     *      JitsiMediaDevicesEvents.PERMISSION_PROMPT_IS_SHOWN should be fired
      * @returns {Promise.<{Array.<JitsiTrack>}, JitsiConferenceError>}
      *     A promise that returns an array of created JitsiTracks if resolved,
      *     or a JitsiConferenceError if rejected.
      */
-    createLocalTracks: function (options) {
-        return RTC.obtainAudioAndVideoPermissions(options || {}).then(
-            function(tracks) {
+    createLocalTracks: function (options, firePermissionPromptIsShownEvent) {
+        var promiseFulfilled = false;
+
+        if (firePermissionPromptIsShownEvent === true) {
+            window.setTimeout(function () {
+                if (!promiseFulfilled) {
+                    var browser = RTCBrowserType.getBrowserType()
+                        .split('rtc_browser.')[1];
+
+                    if (RTCBrowserType.isAndroid()) {
+                        browser = 'android';
+                    }
+
+                    JitsiMediaDevices.emitEvent(
+                        JitsiMediaDevicesEvents.PERMISSION_PROMPT_IS_SHOWN,
+                        browser);
+                }
+            }, USER_MEDIA_PERMISSION_PROMPT_TIMEOUT);
+        }
+
+        return RTC.obtainAudioAndVideoPermissions(options || {})
+            .then(function(tracks) {
+                promiseFulfilled = true;
+
                 if(!RTC.options.disableAudioLevels)
                     for(var i = 0; i < tracks.length; i++) {
                         var track = tracks[i];
@@ -120,8 +148,11 @@ var LibJitsiMeet = {
                                 });
                         }
                     }
+
                 return tracks;
             }).catch(function (error) {
+                promiseFulfilled = true;
+
                 Statistics.sendGetUserMediaFailed(error);
 
                 if(error.name === JitsiTrackErrors.UNSUPPORTED_RESOLUTION) {

doc/API.md

@@ -60,7 +60,7 @@ The ```options``` parameter is JS object with the following properties:
 JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
 ```
 
-* ```JitsiMeetJS.createLocalTracks(options)``` - Creates the media tracks and returns them trough ```Promise``` object. If rejected, passes ```JitsiTrackError``` instance to catch block.
+* ```JitsiMeetJS.createLocalTracks(options, firePermissionPromptIsShownEvent)``` - Creates the media tracks and returns them trough ```Promise``` object. If rejected, passes ```JitsiTrackError``` instance to catch block.
     - options - JS object with configuration options for the local media tracks. You can change the following properties there:
         1. devices - array with the devices - "desktop", "video" and "audio" that will be passed to GUM. If that property is not set GUM will try to get all available devices.
         2. resolution - the prefered resolution for the local video.
@@ -69,6 +69,7 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
         5. minFps - the minimum frame rate for the video stream (passed to GUM)
         6. maxFps - the maximum frame rate for the video stream (passed to GUM)
         7. facingMode - facing mode for a camera (possible values - 'user', 'environment')
+    - firePermissionPromptIsShownEvent - optional boolean parameter. If set to ```true```, ```JitsiMediaDevicesEvents.PERMISSION_PROMPT_IS_SHOWN``` will be fired when browser shows gUM permission prompt.
 
 * ```JitsiMeetJS.enumerateDevices(callback)``` - __DEPRECATED__. Use ```JitsiMeetJS.mediaDevices.enumerateDevices(callback)``` instead.
 * ```JitsiMeetJS.isDeviceListAvailable()``` - __DEPRECATED__. Use ```JitsiMeetJS.mediaDevices.isDeviceListAvailable()``` instead.
@@ -90,27 +91,6 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
     - ```addEventListener(event, handler)``` - attaches an event handler.
     - ```removeEventListener(event, handler)``` - removes an event handler.
 
-* ```JitsiMeetJS.environment``` - environment detection helper. Provides following methods and properties:
-    - ```RTC_BROWSER_CHROME```
-    - ```RTC_BROWSER_OPERA```
-    - ```RTC_BROWSER_FIREFOX```
-    - ```RTC_BROWSER_IEXPLORER```
-    - ```RTC_BROWSER_SAFARI```
-    - ```RTC_BROWSER_NWJS```
-    - ```RTC_BROWSER_REACT_NATIVE```
-    - ```getBrowserType()``` - gets current browser type.
-    - ```isChrome()``` - checks if current browser is Chrome.
-    - ```isOpera()``` - checks if current browser is Opera.
-    - ```isFirefox()``` - checks if current browser is Firefox.
-    - ```isIExplorer()``` - checks if current browser is Internet Explorer.
-    - ```isSafari()``` - checks if current browser is Safari.
-    - ```isNWJS()``` - checks if current environment is NWJS.
-    - ```isReactNative()``` - checks if current environment is React Native.
-    - ```isTemasysPluginUsed()``` - checks if Temasys RTC plugin is used.
-    - ```getFirefoxVersion()``` - returns Firefox version.
-    - ```getChromeVersion()``` - returns Chrome version.
-    - ```isAndroid()``` - checks whether the browser is running on an android device.
-
 * ```JitsiMeetJS.events``` - JS object that contains all events used by the API. You will need that JS object when you try to subscribe for connection or conference events.
     We have two event types - connection and conference. You can access the events with the following code ```JitsiMeetJS.events.<event_type>.<event_name>```.
     For example if you want to use the conference event that is fired when somebody leave conference you can use the following code - ```JitsiMeetJS.events.conference.USER_LEFT```.
@@ -154,6 +134,7 @@ JitsiMeetJS.setLogLevel(JitsiMeetJS.logLevels.ERROR);
 
     4. mediaDevices
         - DEVICE_LIST_CHANGED - indicates that list of currently connected devices has changed (parameters - devices(MediaDeviceInfo[])).
+        - PERMISSION_PROMPT_IS_SHOWN - Indicates that the environment is currently showing permission prompt to access camera and/or microphone (parameters - environmentType ('chrome'|'opera'|'firefox'|'iexplorer'|'safari'|'nwjs'|'react-native'|'android').
 
 
 * ```JitsiMeetJS.errors``` - JS object that contains all errors used by the API. You can use that object to check the reported errors from the API