docs(api.md): Comply with our coding style.

This commit is contained in:
Hristo Terezov 2019-03-29 14:15:53 +00:00
parent 829e5597d5
commit f12317dc59
1 changed files with 125 additions and 116 deletions

View File

@ -7,7 +7,7 @@ You can use the Jitsi Meet API to embed Jitsi Meet in to your application. You a
To embed Jitsi Meet in your application you need to add the Jitsi Meet API library: To embed Jitsi Meet in your application you need to add the Jitsi Meet API library:
```javascript ```javascript
<script src="https://meet.jit.si/external_api.js"></script> <script src='https://meet.jit.si/external_api.js'></script>
``` ```
## API ## API
@ -16,7 +16,7 @@ To embed Jitsi Meet in your application you need to add the Jitsi Meet API libra
The next step for embedding Jitsi Meet is to create the Jitsi Meet API object. The next step for embedding Jitsi Meet is to create the Jitsi Meet API object.
Its constructor gets a number of options: Its constructor gets a number of options:
* **domain**: domain used to build the conference URL, "meet.jit.si" for * **domain**: domain used to build the conference URL, 'meet.jit.si' for
example. example.
* **options**: object with properties - the optional arguments: * **options**: object with properties - the optional arguments:
* **roomName**: (optional) name of the room to join. * **roomName**: (optional) name of the room to join.
@ -34,49 +34,54 @@ Its constructor gets a number of options:
Example: Example:
```javascript ```javascript
var domain = "meet.jit.si"; const domain = 'meet.jit.si';
var options = { const options = {
roomName: "JitsiMeetAPIExample", roomName: 'JitsiMeetAPIExample',
width: 700, width: 700,
height: 700, height: 700,
parentNode: document.querySelector('#meet') parentNode: document.querySelector('#meet')
} };
var api = new JitsiMeetExternalAPI(domain, options); const api = new JitsiMeetExternalAPI(domain, options);
``` ```
You can set the initial media devices for the call: You can set the initial media devices for the call:
```javascript ```javascript
var domain = "meet.jit.si"; const domain = 'meet.jit.si';
var options = { const options = {
... ...
devices: { devices: {
'audioInput': '<deviceLabel>', audioInput: '<deviceLabel>',
'audioOutput': '<deviceLabel>', audioOutput: '<deviceLabel>',
'videoInput': '<deviceLabel>' videoInput: '<deviceLabel>'
} },
} ...
var api = new JitsiMeetExternalAPI(domain, options); };
const api = new JitsiMeetExternalAPI(domain, options);
``` ```
You can overwrite options set in [config.js] and [interface_config.js]. You can overwrite options set in [config.js] and [interface_config.js].
For example, to enable the filmstrip-only interface mode, you can use: For example, to enable the filmstrip-only interface mode, you can use:
```javascript ```javascript
var options = { const options = {
interfaceConfigOverwrite: {filmStripOnly: true} ...
interfaceConfigOverwrite: { filmStripOnly: true },
...
}; };
var api = new JitsiMeetExternalAPI(domain, options); const api = new JitsiMeetExternalAPI(domain, options);
``` ```
You can also pass a jwt token to Jitsi Meet: You can also pass a jwt token to Jitsi Meet:
```javascript ```javascript
var options = { const options = {
jwt: "<jwt_token>", ...
noSsl: false jwt: '<jwt_token>',
noSsl: false,
...
}; };
var api = new JitsiMeetExternalAPI(domain, options); const api = new JitsiMeetExternalAPI(domain, options);
``` ```
### Controlling the embedded Jitsi Meet Conference ### Controlling the embedded Jitsi Meet Conference
@ -85,25 +90,25 @@ Device management `JitsiMeetExternalAPI` methods:
* **getAvailableDevices** - Retrieve a list of available devices. * **getAvailableDevices** - Retrieve a list of available devices.
```javascript ```javascript
api.getAvailableDevices().then(function(devices) { api.getAvailableDevices().then(devices => {
// devices = { // devices = {
// 'audioInput': [{ // audioInput: [{
// deviceId: "ID" // deviceId: 'ID'
// groupId: "grpID" // groupId: 'grpID'
// kind: "audioinput" // kind: 'audioinput'
// label: "Label" // label: 'label'
// },....], // },....],
// 'audioOutput': [{ // audioOutput: [{
// deviceId: "ID" // deviceId: 'ID'
// groupId: "grpID" // groupId: 'grpID'
// kind: "audioOutput" // kind: 'audioOutput'
// label: "Label" // label: 'label'
// },....], // },....],
// 'videoInput': [{ // videoInput: [{
// deviceId: "ID" // deviceId: 'ID'
// groupId: "grpID" // groupId: 'grpID'
// kind: "videoInput" // kind: 'videoInput'
// label: "Label" // label: 'label'
// },....] // },....]
// } // }
... ...
@ -112,25 +117,25 @@ api.getAvailableDevices().then(function(devices) {
* **getCurrentDevices** - Retrieve a list with the devices that are currently selected. * **getCurrentDevices** - Retrieve a list with the devices that are currently selected.
```javascript ```javascript
api.getCurrentDevices().then(function(devices) { api.getCurrentDevices().then(devices => {
// devices = { // devices = {
// 'audioInput': { // audioInput: {
// deviceId: "ID" // deviceId: 'ID'
// groupId: "grpID" // groupId: 'grpID'
// kind: "videoInput" // kind: 'videoInput'
// label: "Label" // label: 'label'
// }, // },
// 'audioOutput': { // audioOutput: {
// deviceId: "ID" // deviceId: 'ID'
// groupId: "grpID" // groupId: 'grpID'
// kind: "videoInput" // kind: 'videoInput'
// label: "Label" // label: 'label'
// }, // },
// 'videoInput': { // videoInput: {
// deviceId: "ID" // deviceId: 'ID'
// groupId: "grpID" // groupId: 'grpID'
// kind: "videoInput" // kind: 'videoInput'
// label: "Label" // label: 'label'
// } // }
// } // }
... ...
@ -140,21 +145,21 @@ api.getCurrentDevices().then(function(devices) {
```javascript ```javascript
// The accepted deviceType values are - 'output', 'input' or undefined. // The accepted deviceType values are - 'output', 'input' or undefined.
api.isDeviceChangeAvailable(deviceType).then(function(isDeviceChangeAvailable) { api.isDeviceChangeAvailable(deviceType).then(isDeviceChangeAvailable => {
... ...
}); });
``` ```
* **isDeviceListAvailable** - Resolves with true if the device list is available and with false if not. * **isDeviceListAvailable** - Resolves with true if the device list is available and with false if not.
```javascript ```javascript
api.isDeviceListAvailable().then(function(isDeviceListAvailable) { api.isDeviceListAvailable().then(isDeviceListAvailable => {
... ...
}); });
``` ```
* **isMultipleAudioInputSupported** - Resolves with true if multiple audio input is supported and with false if not. * **isMultipleAudioInputSupported** - Resolves with true if multiple audio input is supported and with false if not.
```javascript ```javascript
api.isMultipleAudioInputSupported().then(function(isMultipleAudioInputSupported) { api.isMultipleAudioInputSupported().then(isMultipleAudioInputSupported => {
... ...
}); });
``` ```
@ -177,7 +182,7 @@ api.setVideoInputDevice(deviceLabel, deviceId);
You can control the embedded Jitsi Meet conference using the `JitsiMeetExternalAPI` object by using `executeCommand`: You can control the embedded Jitsi Meet conference using the `JitsiMeetExternalAPI` object by using `executeCommand`:
```javascript ```javascript
api.executeCommand(command, ...arguments) api.executeCommand(command, ...arguments);
``` ```
The `command` parameter is String object with the name of the command. The following commands are currently supported: The `command` parameter is String object with the name of the command. The following commands are currently supported:
@ -194,57 +199,60 @@ api.executeCommand('subject', 'New Conference Subject');
* **toggleAudio** - Mutes / unmutes the audio for the local participant. No arguments are required. * **toggleAudio** - Mutes / unmutes the audio for the local participant. No arguments are required.
```javascript ```javascript
api.executeCommand('toggleAudio') api.executeCommand('toggleAudio');
``` ```
* **toggleVideo** - Mutes / unmutes the video for the local participant. No arguments are required. * **toggleVideo** - Mutes / unmutes the video for the local participant. No arguments are required.
```javascript ```javascript
api.executeCommand('toggleVideo') api.executeCommand('toggleVideo');
``` ```
* **toggleFilmStrip** - Hides / shows the filmstrip. No arguments are required. * **toggleFilmStrip** - Hides / shows the filmstrip. No arguments are required.
```javascript ```javascript
api.executeCommand('toggleFilmStrip') api.executeCommand('toggleFilmStrip');
``` ```
* **toggleChat** - Hides / shows the chat. No arguments are required. * **toggleChat** - Hides / shows the chat. No arguments are required.
```javascript ```javascript
api.executeCommand('toggleChat') api.executeCommand('toggleChat');
``` ```
* **toggleShareScreen** - Starts / stops screen sharing. No arguments are required. * **toggleShareScreen** - Starts / stops screen sharing. No arguments are required.
```javascript ```javascript
api.executeCommand('toggleShareScreen') api.executeCommand('toggleShareScreen');
``` ```
* **hangup** - Hangups the call. No arguments are required. * **hangup** - Hangups the call. No arguments are required.
```javascript ```javascript
api.executeCommand('hangup') api.executeCommand('hangup');
``` ```
* **email** - Changes the local email address. This command requires one argument - the new email address to be set. * **email** - Changes the local email address. This command requires one argument - the new email address to be set.
```javascript ```javascript
api.executeCommand('email', 'example@example.com') api.executeCommand('email', 'example@example.com');
``` ```
* **avatarUrl** - Changes the local avatar URL. This command requires one argument - the new avatar URL to be set. * **avatarUrl** - Changes the local avatar URL. This command requires one argument - the new avatar URL to be set.
```javascript ```javascript
api.executeCommand('avatarUrl', 'https://avatars0.githubusercontent.com/u/3671647') api.executeCommand('avatarUrl', 'https://avatars0.githubusercontent.com/u/3671647');
``` ```
You can also execute multiple commands using the `executeCommands` method: You can also execute multiple commands using the `executeCommands` method:
```javascript ```javascript
api.executeCommands(commands) api.executeCommands(commands);
``` ```
The `commands` parameter is an object with the names of the commands as keys and the arguments for the commands as values: The `commands` parameter is an object with the names of the commands as keys and the arguments for the commands as values:
```javascript ```javascript
api.executeCommands({displayName: ['nickname'], toggleAudio: []}); api.executeCommands({
displayName: [ 'nickname' ],
toggleAudio: []
});
``` ```
You can add event listeners to the embedded Jitsi Meet using the `addEventListener` method. You can add event listeners to the embedded Jitsi Meet using the `addEventListener` method.
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods (`addListener` or `on`).** **NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods (`addListener` or `on`).**
```javascript ```javascript
api.addEventListener(event, listener) api.addEventListener(event, listener);
``` ```
The `event` parameter is a String object with the name of the event. The `event` parameter is a String object with the name of the event.
@ -255,36 +263,36 @@ The following events are currently supported:
changes. The listener will receive an object with the following structure: changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"id": id, // the id of the participant that changed his avatar. id: string, // the id of the participant that changed his avatar.
"avatarURL": avatarURL // the new avatar URL. avatarURL: string // the new avatar URL.
} }
``` ```
* **audioAvailabilityChanged** - event notifications about audio availability status changes. The listener will receive an object with the following structure: * **audioAvailabilityChanged** - event notifications about audio availability status changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"available": available // new available status - boolean available: boolean // new available status - boolean
} }
``` ```
* **audioMuteStatusChanged** - event notifications about audio mute status changes. The listener will receive an object with the following structure: * **audioMuteStatusChanged** - event notifications about audio mute status changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"muted": muted // new muted status - boolean muted: boolean // new muted status - boolean
} }
``` ```
* **screenSharingStatusChanged** - receives event notifications about turning on/off the local user screen sharing. The listener will receive object with the following structure: * **screenSharingStatusChanged** - receives event notifications about turning on/off the local user screen sharing. The listener will receive object with the following structure:
```javascript ```javascript
{ {
"on": on, //whether screen sharing is on on: boolean, //whether screen sharing is on
"details": { details: {
// From where the screen sharing is capturing, if known. Values which are // From where the screen sharing is capturing, if known. Values which are
// passed include "window", "screen", "proxy", "device". The value undefined // passed include 'window', 'screen', 'proxy', 'device'. The value undefined
// will be passed if the source type is unknown or screen share is off. // will be passed if the source type is unknown or screen share is off.
sourceType: sourceType sourceType: string|undefined
} }
} }
``` ```
@ -292,9 +300,9 @@ changes. The listener will receive an object with the following structure:
messages. The listener will receive an object with the following structure: messages. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"from": from, // The id of the user that sent the message from: string, // The id of the user that sent the message
"nick": nick, // the nickname of the user that sent the message nick: string, // the nickname of the user that sent the message
"message": txt // the text of the message message: string // the text of the message
} }
``` ```
@ -302,7 +310,7 @@ messages. The listener will receive an object with the following structure:
messages. The listener will receive an object with the following structure: messages. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"message": txt // the text of the message message: string // the text of the message
} }
``` ```
@ -310,15 +318,15 @@ messages. The listener will receive an object with the following structure:
changes. The listener will receive an object with the following structure: changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"id": id, // the id of the participant that changed his display name id: string, // the id of the participant that changed his display name
"displayname": displayName // the new display name displayname: string // the new display name
} }
``` ```
* **deviceListChanged** - event notifications about device list changes. The listener will receive an object with the following structure: * **deviceListChanged** - event notifications about device list changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"devices": devices // the new list of available devices. devices: Object // the new list of available devices.
} }
``` ```
NOTE: The devices object has the same format as the getAvailableDevices result format. NOTE: The devices object has the same format as the getAvailableDevices result format.
@ -327,60 +335,60 @@ NOTE: The devices object has the same format as the getAvailableDevices result f
changes. The listener will receive an object with the following structure: changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"id": id, // the id of the participant that changed his email id: string, // the id of the participant that changed his email
"email": email // the new email email: string // the new email
} }
``` ```
* **filmstripDisplayChanged** - event notifications about the visibility of the filmstrip being updated. * **filmstripDisplayChanged** - event notifications about the visibility of the filmstrip being updated.
```javascript ```javascript
{ {
"visible": visible, // Whether or not the filmstrip is displayed or hidden. visible: boolean // Whether or not the filmstrip is displayed or hidden.
} }
``` ```
* **participantJoined** - event notifications about new participants who join the room. The listener will receive an object with the following structure: * **participantJoined** - event notifications about new participants who join the room. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"id": id, // the id of the participant id: string, // the id of the participant
"displayName": displayName // the display name of the participant displayName: string // the display name of the participant
} }
``` ```
* **participantLeft** - event notifications about participants that leave the room. The listener will receive an object with the following structure: * **participantLeft** - event notifications about participants that leave the room. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"id": id // the id of the participant id: string // the id of the participant
} }
``` ```
* **videoConferenceJoined** - event notifications fired when the local user has joined the video conference. The listener will receive an object with the following structure: * **videoConferenceJoined** - event notifications fired when the local user has joined the video conference. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"roomName": room, // the room name of the conference roomName: string, // the room name of the conference
"id": id, // the id of the local participant id: string, // the id of the local participant
"displayName": displayName, // the display name of the local participant displayName: string, // the display name of the local participant
"avatarURL": avatarURL // the avatar URL of the local participant avatarURL: string // the avatar URL of the local participant
} }
``` ```
* **videoConferenceLeft** - event notifications fired when the local user has left the video conference. The listener will receive an object with the following structure: * **videoConferenceLeft** - event notifications fired when the local user has left the video conference. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"roomName": room // the room name of the conference roomName: string // the room name of the conference
} }
``` ```
* **videoAvailabilityChanged** - event notifications about video availability status changes. The listener will receive an object with the following structure: * **videoAvailabilityChanged** - event notifications about video availability status changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"available": available // new available status - boolean available: boolean // new available status - boolean
} }
``` ```
* **videoMuteStatusChanged** - event notifications about video mute status changes. The listener will receive an object with the following structure: * **videoMuteStatusChanged** - event notifications about video mute status changes. The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"muted": muted // new muted status - boolean muted: boolean // new muted status - boolean
} }
``` ```
@ -390,7 +398,7 @@ changes. The listener will receive an object with the following structure:
The listener will receive an object with the following structure: The listener will receive an object with the following structure:
```javascript ```javascript
{ {
"subject": subject // the new subject subject: string // the new subject
} }
``` ```
@ -412,79 +420,80 @@ function outgoingMessageListener(object)
api.addEventListeners({ api.addEventListeners({
incomingMessage: incomingMessageListener, incomingMessage: incomingMessageListener,
outgoingMessage: outgoingMessageListener}) outgoingMessage: outgoingMessageListener
});
``` ```
If you want to remove a listener you can use `removeEventListener` method with argument the name of the event. If you want to remove a listener you can use `removeEventListener` method with argument the name of the event.
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods( `removeListener`).** **NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods( `removeListener`).**
```javascript ```javascript
api.removeEventListener("incomingMessage"); api.removeEventListener('incomingMessage');
``` ```
If you want to remove more than one event you can use `removeEventListeners` method with an Array with the names of the events as an argument. If you want to remove more than one event you can use `removeEventListeners` method with an Array with the names of the events as an argument.
**NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods.** **NOTE: This method still exists but it is deprecated. JitsiMeetExternalAPI class extends [EventEmitter]. Use [EventEmitter] methods.**
```javascript ```javascript
api.removeEventListeners(["incomingMessage", "outgoingMessageListener"]); api.removeEventListeners([ 'incomingMessage', 'outgoingMessageListener' ]);
``` ```
You can get the number of participants in the conference with the following API function: You can get the number of participants in the conference with the following API function:
```javascript ```javascript
var numberOfParticipants = api.getNumberOfParticipants(); const numberOfParticipants = api.getNumberOfParticipants();
``` ```
You can get the avatar URL of a participant in the conference with the following API function: You can get the avatar URL of a participant in the conference with the following API function:
```javascript ```javascript
var avatarURL = api.getAvatarURL(participantId); const avatarURL = api.getAvatarURL(participantId);
``` ```
You can get the display name of a participant in the conference with the following API function: You can get the display name of a participant in the conference with the following API function:
```javascript ```javascript
var displayName = api.getDisplayName(participantId); const displayName = api.getDisplayName(participantId);
``` ```
You can get the email of a participant in the conference with the following API function: You can get the email of a participant in the conference with the following API function:
```javascript ```javascript
var email = api.getEmail(participantId); const email = api.getEmail(participantId);
``` ```
You can get the iframe HTML element where Jitsi Meet is loaded with the following API function: You can get the iframe HTML element where Jitsi Meet is loaded with the following API function:
```javascript ```javascript
var iframe = api.getIFrame(); const iframe = api.getIFrame();
``` ```
You can check whether the audio is muted with the following API function: You can check whether the audio is muted with the following API function:
```javascript ```javascript
api.isAudioMuted().then(function(muted) { api.isAudioMuted().then(muted => {
... ...
}); });
``` ```
You can check whether the video is muted with the following API function: You can check whether the video is muted with the following API function:
```javascript ```javascript
api.isVideoMuted().then(function(muted) { api.isVideoMuted().then(muted => {
... ...
}); });
``` ```
You can check whether the audio is available with the following API function: You can check whether the audio is available with the following API function:
```javascript ```javascript
api.isAudioAvailable().then(function(available) { api.isAudioAvailable().then(available => {
... ...
}); });
``` ```
You can check whether the video is available with the following API function: You can check whether the video is available with the following API function:
```javascript ```javascript
api.isVideoAvailable().then(function(available) { api.isVideoAvailable().then(available => {
... ...
}); });
``` ```
You can invite new participants to the call with the following API function: You can invite new participants to the call with the following API function:
```javascript ```javascript
api.invite([{...}, {...}, {...}]).then(function() { api.invite([ {...}, {...}, {...} ]).then(() => {
// success // success
}).catch(function() { }).catch(() => {
// failure // failure
}); });
``` ```
@ -492,7 +501,7 @@ api.invite([{...}, {...}, {...}]).then(function() {
You can remove the embedded Jitsi Meet Conference with the following API function: You can remove the embedded Jitsi Meet Conference with the following API function:
```javascript ```javascript
api.dispose() api.dispose();
``` ```
NOTE: It's a good practice to remove the conference before the page is unloaded. NOTE: It's a good practice to remove the conference before the page is unloaded.