API Object

When a plugin gets loaded in the Coviu platform the Coviu codebase sends some methods to the plugin via an object called api

This api object helps you to use methods from Coviu for easier development of the plugin.

Below is the list of the attributes the api objects holds.

api.version()

Returns an object with the area the plugin is loaded along with the version.

{
    type: either call or waiting area,
    version: Version of the module
}

api.account.getRooms()

Returns all the rooms belonging to the current team.

api.resources

api.resources exposes a number of methods that assist with management of resources
among exposed methods are ones for registering ,rendering, adding, listing resource as well as others

exposed methods :

add: ƒ add(type, opts)
get: ƒ ()
getCache: ƒ ()
isActive: ƒ ()
isContentAvailable: ƒ ()
list: ƒ list()
newCache: ƒ ()
observe: ƒ ()
received: ƒ received(id)
registerDocument: ƒ register(doc)
registerHandler: ƒ register(handler)
registerRenderer: ƒ register(renderer)
setEnabled: ƒ setEnabled(ref, enabled)
streamable: ƒ streamable(opts)
transaction: ƒ ()
transmit: ƒ ()
waitForCache: ƒ waitForCache(id)

api.resources.registerHandler

Registers a new resource handler to handle processing of resources with a given type. This will allow resources to response to setup/enable/disable/destroy actions

input parameters

input parameters
register handler methods accepts a handler class which defines how to handle different stages of life cycle for a resource of specific resource type within a call a handler class that is passed to register handler method typically will define below actions/functions but can also have others according to resource type and functionality add : The `add` function is called when a user attempts to create a new resource of specified resource type setup : The `setup` function is called when a resource is initialised enable : The `enable` function is called when an item is triggered as the active resource in the resource view. This allows you to reactivate any necessary components that are required for the resource to do its work disable : The `disable` function is called when an item is removed and is no longer an active resource in the resource view, allowing appropriate deallocation of resources that aren't needed while the resource is not in the forefront. * remove : The `remove` function is called when a resource is deleted.

register handler methods accepts a handler class which defines how to handle different stages of life cycle for a resource of specific resource type within a call

a handler class that is passed to register handler method typically will define below actions/functions but can also have others according to resource type and functionality

add : The add function is called when a user attempts to create a new resource of specified resource type
setup : The setup function is called when a resource is initialised
enable : The enable function is called when an item is triggered as the active resource in the resource view. This allows you to reactivate any necessary components that are required for the resource to do its work
disable : The disable function is called when an item is removed and is no longer an active resource in the resource view, allowing appropriate deallocation of resources that aren't needed while the resource is not in the forefront.
* remove : The remove function is called when a resource is deleted.

Sample code

/* at the root of the plugin, define the plugin function which is called when plugin is activated by Coviu platform */

function plugin(api) {

/* register the different types of handlers required for the plugin
*/
    return Promise.all([

   /*call "api.resources.registerHandler" and pass the 
   handler class which takes api object as parameter */

        api.resources.registerHandler(handler(api)),

   // register other handlers
        api.resources.registerRenderer(renderer(api)),
        api.resources.registerDocument(doc)
    ]).then(() => {
        return {
            /* specify the name property to assign for this plugin */
            name: 'Plugin Name'
        };
    });
}

/** sample resource handler class {"handler.js"} **/

module.exports = function(api) {

	const { h } = api.render;

	let _handler = {};

	// set the resource type for handler
	_handler.id = RESOURCE_TYPE;

    /* create all methods reuired to handle the resource : add / setup / enable / disbale / remove */

	/** The `add` function **/
    // passing resources & options object  to use for creation of new item of this resource type
	_handler.add = (resources, opts) => {

		return new Promise((resolve, reject) => {
			const ownerId = api.local.id();
			const { store } = resources;

			// Add the steps required for adding a new  resource
			let item = resources.methods.newResourceItem({
				category: _handler.id,
				owner: ownerId,
				metadata: { title: displayText(opts.title)},
				recipients: recipients,
				options: { },
				selected: !store.active(),
				type: _handler.id
			});

			return resolve(item);
		});
	};

	/** The `setup` function  **/
	_handler.setup = (item) => {
		// steps to execute/apply when resource is initialized
	};

	/** The	`enable` function **/
	_handler.enable = (item) => {
		// steps to execute/apply when resource is the  active resource
	};

	/** The `disable` function **/
	_handler.disable = (item) => {
	    // steps to execute/apply when resource is the removed from resource view & no longer active 
	};

	/** The `remove` function **/
	_handler.remove = (core, resources, item) => {
		// steps to execute/apply when resource deleted
    };
	return _handler;
}

api.resources.registerRenderer

Registers a new resource renderer. A resource renderer is used to render resources of a given type and takes a render class as an input parameter.

input parameters

input parameters
registerRenderer method accepts a renderer class as an input parameter which defines how the resource gets rendered when it is the active resource a renderer class that is passed to register handler method typically will define below actions/functions but can also have others according to resource type and functionality activate : The `activate` function is called when resource is added view : The view to render * renderCustomInterface : a custom interface to render fo this resource

registerRenderer method accepts a renderer class as an input parameter which defines how the resource gets rendered when it is the active resource

a renderer class that is passed to register handler method typically will define below actions/functions but can also have others according to resource type and functionality

activate : The activate function is called when resource is added
view : The view to render
* renderCustomInterface : a custom interface to render fo this resource

Sample code

/* at the root of the plugin, define the plugin function which is called when plugin is activated by Coviu platform */

function plugin(api) {

/* register the different types of handlers required for the plugin
*/
    return Promise.all([

   /*call "api.resources.registerRenderer" and pass the 
   handler class which takes api object as parameter */
    
     api.resources.registerRenderer(renderer(api)),
        
   // register other handlers
        api.resources.registerHandler(handler(api)),
        api.resources.registerDocument(doc)
    ]).then(() => {
        return {
            /* specify the name property to assign for this plugin */
            name: 'Plugin Name'
        };
    });
}

/** sample resource handler class {"renderer.js"} **/

module.exports = api => {
    // get mercury and thunk from api.render
	const { h, thunk } = api.render;
	const render = app(api);

    return {
        id: constants.id,
        label: 'Plugin name',
        description: 'Plugin short description',

        // define activate method which add the resource
        activate: () => {
            api.resources.add(constants.id, {title: 'Plugin name'});
        },

		/** Indicate whether the resource resolution should be automatically scaled **/
		preventResolutionUpdate: (resource) => {
			return false;
		},

		/** Indicates whether or not to render a custom interface **/
		requiresCustomInterface: function(resource) {
			return true;
		},

		/** define View funtion to  Render a view into the standard scaled resource view (toolbar/zoom/etc)  **/
		view: (resource, cache, resourceMethods, documentSizeCb, position, availableSpace) => {
			return h('div', 'This div is rendered in the standard scaled resource view');
        },
        
        /**  If a custom interface is required, render a custom interface **/
		renderCustomInterface: () => {
            // define the options to use for render of custom interface

			return thunk(`customInterface`, {
				resource: resource,
				cache: cache,
				height: availableSpace.height,
				width: availableSpace.width
			}, () => render({ resource, state: cache, position, availableSpace, cache: updater }))
		}
    }
}

api.resources.registerDocument

Registers a new resource document.

api.resources.add

Adds a new resource to the current call session

api.resources.received(id)

Indicate a resource has been received

api.resources.list()

This method returns the list of items. Items are the synchronizable resource state sent over the mesh

api.resources.get

Gets a resource thorough its id

api.resources.isActive

Returns true if the resource with the given ID is active

api.resources.observe

api.resources.getCache

Returns the item that has been already cached

api.resources.newCache

Adds a new resource to the cache

api.resources.setEnabled

Disables a resource by reference

api.resources.isContentAvailable

This method is to check if the resources are available

api.resources.transmit

This method will transmit the contents of a resource cache to other peers

api.resources.waitForCache(id)

Waits for the cache for a given item ID to be available

api.resources.transaction

This method helps in transacting resources between peers.

api.resources.streamable

Streamable provides a base handler implementation for streaming resources

api.render.h

Used to render a Mercury VirtualNode (equivalent of mercury.h), which is the basis of Coviu's rendering engine. Used to create a VirtualDom tree representation that will indicate how to render a display

api.render.node

api.render.thunk

Used to create a rendering thunk, which compare a set of input objects, and only call the provided render function if the state has changed since the last execution of the function. To be used in creating more efficiently rendering plugin views.

api.render.resource

This method helps in rendering the document resource in the plugin

api.render.stream

This method returns a media stream.

api.render.Tooltip

Renders a ToolTip component which is developed in Coviu Platform and is compatible with the design standards.

api.render.ToolbarButton

Renders a ToolbarButton component which is developed in Coviu Platform and is compatible with the design standards.

api.render.ToolbarDropdown

Renders a ToolbarDropdown component which is developed in Coviu Platform and is compatible with the design standards.

api.render.DrawerToggle

Renders a DrawerToggle component which is developed in Coviu Platform and is compatible with the design standards.

api.render.DrawerHelp

Renders a DrawerHelp component which is developed in Coviu Platform and is compatible with the design standards.

api.render.CopyableLink

Renders a CopyableLink component which is developed in Coviu Platform and is compatible with the design standards.

api.render.Toggle

Renders a Toggle component which is developed in Coviu Platform and is compatible with the design standards.

api.render.PhoneNumberInput

Renders a PhoneNumberInput component which is developed in Coviu Platform and is compatible with the design standards.

api.render.DialPad

Renders a DialPad component which is developed in Coviu Platform and is compatible with the design standards.

api.render.DialpadNumberInput

Renders a DialpadNumberInput component which is developed in Coviu Platform and is compatible with the design standards.

api.render.pagination

Renders a pagination component which is developed in Coviu Platform and is compatible with the design standards.

api.state.participants

This methods returns a list of current call participants each represented as an object holding all participant state info

Input parameters / return values
no input parameters required for this method
method returns a list of participant objects , each object represents a collection of info for a participant browser: object {name: string , version: string} displayName: string entered: timestamp ident: string isHost: boolean mute: {audio: boolean , video: boolean} phone: string state: string stream: string streamTimestamp: string usid: string example return value : behaviour: "normal" browser: {name: "chrome", version: "87.0.4280"} displayName: "karim" entered: 1613613918607 ident: "caller1" isHost: true mute: {audio: true , video: true} phone: null state: null stream: null streamTimestamp: null usid: "*******00033g6l9m4a3be7"

Input parameters / return values

no input parameters required for this method

method returns a list of participant objects , each object represents a collection of info for a participant
browser: object {name: string , version: string}
displayName: string
entered: timestamp
ident: string
isHost: boolean
mute: {audio: boolean , video: boolean}
phone: string
state: string
stream: string
streamTimestamp: string
usid: string

example return value :
behaviour: "normal"
browser: {name: "chrome", version: "87.0.4280"}
displayName: "karim"
entered: 1613613918607
ident: "caller1"
isHost: true
mute: {audio: true , video: true}
phone: null
state: null
stream: null
streamTimestamp: null
usid: "***00033g6l9m4a3be7"

Sample code

// get a list of participants 
let participants = api.state.participants();

// find call participant how is the resource owner
let localId = api.local.id();
let owner = api.state.participants()[localId];

api.state.callStatus

Returns an object representing current call status, used to store call information

no input or output parameters required

api.file.read

This method is used to retrieve the file data.

api.file.download

This method is used to download the file from a URL

api.collections.save

This method is used to save the plugin configuration in Coviu's database.

api.media.devices

Returns a Promise that will contain an enumerated list of the local devices input and output devices

api.media.request

Requests a camera source ID using the camera selector

api.media.addStream

Adds a stream to this peers local streams. If a call is currently ongoing, it will be automatically added to the call. Otherwise, the stream will be added automatically when a call starts.

api.media.removeStream

Removes a stream from this peers local streams, which will also result in call connections being renegotiated to remove this stream from the current call

api.media.onLocalStreamChange

Attaches an event listener that will get called whenever a change is detected in any of the current local media streams.

api.media.toggleTracks

Toggles media tracks on a media stream on/off

api.media.sendAudioElementToOutputDevice

Synchronizes an audio element to an output device

api.local.id

Returns a unique UUID

api.local.access

Returns true if the local user is the owner of the room

api.local.browser

This method clones the browser object

api.animations.enable

This method enables animations

api.animations.disable

This method disables animations

api.tools.registerTool

Registers a new tool handler, if a handler with the given ID does not already exists. Will return a de-registration handle function which can be used to deregister the resource handler

api.tools.registerToolGroup

Registers a new tool group which is basically just an entry indicating where tools can register themselves into. If a tool group is already registered, this fails

api.tools.enable(id)

Enables the tool with the given ID.

api.tools.disable(id)

Disables the tool with the given ID.

api.tools.toggle

Toggles the tool active state to the opposite state

api.tools.data(id)

Returns the tool data

api.tools.isEnabled(id)

Returns true if the tool is enabled.

api.tools.setGroup

This method is used to assign a tool to a group.

api.annotations.register

Registers a new annotator handler, if a handler with the given ID does not already exists. Will return a deregistration handle function which can be used to deregister the annotator

api.annotations.add

This method adds a new annotation to the annotations mesh

api.annotations.get

Gets an annotation with the matching ID, or null

api.annotations.transaction(id)

Applies the updates to an annotation

api.annotations.remove(id)

Removes the annotation with the given id

api.annotations.current

Returns an array containing the current annotations on the current context of the active resource. If no annotations are found, an empty array is returned

api.layers.registerLayerHandler

Registers a new layer handler, if a handler with the given ID does not already exists. Will return a de-registration handle function which can be used to deregister the layer

api.layers.newLocalLayer(opts)

Creates a new local layer. Local layers are only applied to the current peer

api.layers.newSharedLayer(opts)

Creates a new shared layer. Shared layers are synchronized across the mesh and so are displayed on all peers in the connection

api.layers.getLayer(id)

Returns the layer's state

api.layers.updateLayer(id, data)

Updates a layer's data. If shared, this updates the mesh row, otherwise updates the state directly

api.layers.removeLayer(id)

Removes a layer. If shared, this updates the mesh row, otherwise updates the state directly

api.mesh.request

Allow the creation of meshes that are used for cross clien-side communication

api.drawers.registerDrawer

Registers a new drawer, if a drawer handler with the given ID does not already exists. Will return a de-registration handle function which can be used to deregister the layer

api.drawers.open

Opens the drawer.

api.drawers.close

Closes the drawer.

api.settings.get(pluginId)

Returns the plugin's configuration from Coviu's database.

api.settings.save(pluginId)

Saves the plugin's configuration into Coviu's database.

api.views.register

Registers a view for the plugin.

api.call.hasOwnerAccess

Returns true if the current participant has owner permissions.

api.call.hasRoomAccess

Returns true if the current participant has room access.

api.call.requestAccess

This creates a new access request. Handlers for the various outcomes can be provided in the options.

api.call.accessController

Access request handler can be used by owners to approve/deny connection requests

api.call.authorise

Provides access to the room for the current participant.

api.call.newSession

Creates a new session if the current participant has owner access. If not session cannot be created.

api.call.join

Enables the current participant to join a call.

api.call.participants

Returns all the participants in the current call.

Input parameters / return values
no input parameters required for this method
method returns an array of participant objects , each object represents a collection of info for each participant browser: object {name: string , version: string} displayName: string entered: timestamp id: string ident: string image: string * isHost: boolean example return value : browser: {name: "chrome", version: "87.0.4280"} displayName: "The host" entered: 1613436074381 id: "gy000053g6f388ym63l" ident: "caller1" image: "https:///*/**.jpg" isHost: true

Input parameters / return values

no input parameters required for this method

method returns an array of participant objects , each object represents a collection of info for each participant
browser: object {name: string , version: string}
displayName: string
entered: timestamp
id: string
ident: string
image: string
* isHost: boolean

example return value :
browser: {name: "chrome", version: "87.0.4280"}
displayName: "The host"
entered: 1613436074381
id: "*gy000053g6f388ym63l"
ident: "caller1"
image: "https://**/**/**.jpg"
isHost: true

Sample code

// call "api.call.participants" to get a list of the    // current call participants and sort the list based on // time of joining the call

const participants = api.call
      .participants()
      .filter(p => p.id !== api.local.id())
      .sort((a, b) => {
        const identA = extractIdent(a);
        const identB = extractIdent(b);

        return identA - identB;
      });

    // find the participant that entered the call first 
    // (note here Coviu host is excluded in previous step via 
    // filter function)
    const earliestParticipant = participants[0];

    // find the earliest host joined the call
    const earliestHost = participants.filter(p => 
    p.isHost)[0];

api.call.location

Returns the browser URL which will be mostly the link to join the call

api.call.info

Returns the information regarding the current room

api.call.forward

Forwards the call to a particular call url. The supplied data is converted into base64 and embedded into the URL hash

api.call.reload

Reloads the call

api.call.supportedOperations

Returns the list of supported operations for this call

api.call.hangup

Hangup initiates the hangup procedure for the application if the participant has owner access

api.call.leave

Leaves the call and cleans up after itself - shuts down the local media capture and terminates the connection to the signaller

api.call.terminate

Instructs a peer (if the current user is a host) to end their call.

api.call.getTransferTargets

Gets the applicable transfer targets, for the participant target given by participantId

api.call.transfer

Transfers a peer to another call location

api.call.createInvite

Creates an Invite for the current call which will always be a URL to join the call.

api.call.addParticipant

Adds a participant to the current call.

api.call.performTransfer

Performs a transfer using a target ID from getTransferTargets

api.call.getMoveTargets

Gets the applicable call movement targets, for the participant target given by participantId

api.call.moveCall

Moves a call to the given transfer target

api.call.getMediaForParticipant(participantId)

This method takes in the participant ID and returns the media streams based on the participant ID.

A Json Object will be returned and that Object contains all the information regarding the media streams.

const participants = api.call.participants();
const firstParticipant = participants[0];

const mediaStream = api.call.getMediaForParticipant(firstParticipant.id);
console.log(mediaStream);

api.call.end

End the call only if the participant is an owner

api.call.supportsFeature

Attempts to determine whether a feature is support for this given room. This is used to allow the call interface and plugins to turn features off/on according to feature limits.

api.call.getFeature

Returns all the supported features.

api.call.getCallType

Returns the call type

api.call.getFocusedParticipant

Returns the UID of the focused stream or null if not focused

api.call.setFocusedParticipant

Set a focused stream

api.call.getMaximumCallParticipants

Returns maximum possible connections for a particular call

api.call.timeStarted

Returns the start time of the call

api.caller.details

Returns the details of the caller only if the participant has owner access

api.modals.open

Opens a modal

api.modals.close(id)

Closes the modal with the given ID

api.alerts.create

Creates a new alert

api.alerts.remove(id)

Removes the alert

api.sounds.play

Toggle the state of an audio item to playing

api.sounds.stop

Stops the sound

api.user.hasSignedOut

Returns true if the user has signed out.

api.user.name

Displays the user name.

api.user.role

Returns the current role of the user.

api.webhooks.trigger

Triggers a webhook. More details present in the Webhooks Documentation.

api.validation.checkPhoneNumber(phoneNumber)

Validates the given phone number.

api.fullScreen.watch

Returns whether the screen is full screening the current panel

api.fullScreen.request

Requests full screen access for the current panel.

api.fullScreen.enabled

Returns true if full screen is enabled for the current panel

api.fullScreen.cancel

Exit the full screen