Let's integrate our SDK in few minutes

Quick Start#

Call SDKs for Javascript#

With CONTUS MirrorFly Call SDK for web, you can easily add real-time calls features to your client app within 30 minutes.

Through our client SDK, you can initialize and configure calls into your app with minimal efforts.

note

If you're looking for the fastest way to build your app’s UI with MirrorFly Call SDK, you can use our sample apps. To get our sample apps, click here

Getting Started#

Supported browsers#

Browser	Supported versions
Edge	13 or higher
Chrome	16 or higher
Firefox	11 or higher
Safari	7 or higher

Things To Be Noted Before You Get Started#

SDK License Key#

caution

Skip this part if you are already having your license key.

To integrate MirrorFly Call SDK into your app, you will need a SDK License Key. The MirrorFly server will use this license key to authenticate the SDK in your application.

To get the License Key,#

Step 1: Register here to get a MirrorFly User account. Registration is subject to verification and would take up to 24 hours.

Step 2: Login to your Account

Step 3: Get the License key from the application Info’ section

license-key

Integrate Call SDK into Your Javascript App#

CONTUS MirrorFly Call for JavaScript, makes the in-app call development process easy with all the essential messaging features

Since it’s the core of all the languages - Importing JavaScript into the application is the fundamental step to proceed further before using any language.

Integrate Using Npm package#

note

Install mirrorfly-sdk (https://www.npmjs.com/package/mirrorfly-sdk) npm package by using the below command

Step 1: Install Mirrorfly Sdk in your application

npm i mirrorfly-sdk

Step 2: Import the SDK into your application where you want

import * as SDK from "mirrorfly-sdk";

Call SDK Integration for Javascript#

warning

Skip this part if you are already installed the SDK using NPM.

Step 1: To download the files from the JavaScript SDKs, click on the Download button.

Download SDK Files

Download

Step 2: Extract the files from the downloaded zip file and copy them into your application.

Step 3: Once the file has been copied, include the script file into your index.html

<script src="./index.js"></script>

Step 4: Now you have the SDK object available in your application to proceed further with initialization.

Step 5: Once, you have successfully got the SDK into your application. It’s time to go with your client’s preferred language implementation.

Terminology#

The below are the common keywords/terminologies used in SDKs with their descriptions

Keyword	Description
`userId`	Unique ID assigned for each user Ex: 12345678 (any alphanumeric). The below characters is not allowed in userId: U+0022 (") U+0026 (&) U+0027 (') U+002F (/) U+003A (:) U+003C (<) U+003E (>) U+0040 (@) userID should follow below specification: https://xmpp.org/extensions/xep-0106.html
`userJid`	userID+@+domain of the chat server Ex. 12345678@xmpp.chatsystem.dev.contus.us
`groupJid`	Unique ID assigned for each group Ex: group123456 (any alphanumeric). GroupJID = groupID +@mix.+domain of the chat server Ex: group123456@mix.xmpp.mirrorfly.dev.contus.us`

Initialize Call SDK#

caution

If you already initialized the SDK, you can add the below callback listeners to receive call related events.

To begin with the initialization process of the call SDK you are required to have certain data that responds to the changes in the connection status in the client's app.

Now, paste the license key on the licensekey param and use the below given method to pass these data through the SDK for further processing.

note

When you are in the trial mode, by default the sandbox servers will be used. After purchase it will be upgraded to dedicated server.

const incomingCallListener = (res) => {};
const callStatusListener = (res) => {};
const userTrackListener = (res) => {};
const muteStatusListener = (res) => {};
const missedCallListener = (res) => {};
const callSwitchListener = (res) => {};
const inviteUsersListener = (res) => {};
const mediaErrorListener = (res) => {};
const callSpeakingListener = (res) => {};
const callUsersUpdateListener = (res) => {};
const callUserJoinedListener = (res) => {};
const callUserLeftListener = (res) => {};
const helper = {}

const initializeObj = {
  licenseKey: "XXXXXXXXXXXXXXXXX",
  callbackListeners: {
    connectionListener,
    incomingCallListener,
    callStatusListener,
    userTrackListener,
    muteStatusListener,
    missedCallListener,
    callSwitchListener,
    inviteUsersListener,
    mediaErrorListener,
    callSpeakingListener,
    callUsersUpdateListener,
    callUserJoinedListener,
    callUserLeftListener,
    helper
  },
};

await SDK.initializeSDK(initializeObj);

Request Params#

Arguments	Description	Type	Required
licenseKey	Mirrorfly's License Key	String	true
callbackListeners	Check here for callback listerners	Object	true

Response Params#

Arguments	Description	Type
statusCode	Status Code	Number
message	Success/Error Message	String

Create a User#

caution

Skip this part if you are already integrated the register and connect method.

Register User#

Step 1: You can use the below given method to register a new user.

Step 2: Once you are registered, you will be provided with a username and password that you can utilize to make the connection with the server via connect method.

await SDK.register(`USER_IDENTIFIER`);

Request Params#

Status	Description	Type	Required
`USER_IDENTIFIER`	Unique Id to Register the User. User identifier can only contain lowercase alphanumeric characters, hyphens (-), and underscores (_)	String	true
`FORCE_REGISTER`	`default value true` provide `true` to force the old session logged out when the registered user has reached the maximum number of multiple-sessions or provide `false` to allow registration till the maximum no of multiple-sessions reached	Boolean	false
`registerMetaData`	`registerMetaData` is an optional parameter to provide MetaData of user. `Maximum size is 3`	Object	false

Request Input for registerMetaData#

Arguments	Description	Type
key	Name of the Key	String
value	Name of the value	String or Boolean or Number

caution

If FORCE_REGISTER is false and if it reached the maximum no of multiple-sessions, then registration will not success and it will throw a 405 exception. Either FORCE_REGISTER should be true or one of the existing session need to be logged out to continue registration.

Response Params#

Arguments	Description	Type
statusCode	Status Code	Number
message	Success/Error Message	String
data	Username, Password, isProfileUpdated, isSandbox, userJid	Object

Sample Response:#

{
  statusCode: 200,
  message: "Success",
  data: {
    username: "123456789",
    password: "987654321",
    isProfileUpdated: true,
    isSandbox: true,
    userJid: "1234567890@xmppdomain"
  }
}

caution

username is the unique id that allows you to connect with other users to send or receive messages.

Connect to MirrorFly Server#

Step 1: You can use the credentials that you have obtained while registration to make the connection with the server.

Step 2: Once you have created the connection successfully, you will be responded with an approval message as ‘statusCode of 200’ or else will get an execution error.

Step 3: With this you can also trace the connection status that you receive in connectionListener callback function.

Step 4: If you face any error while making a connection with the server, you will receive an error message with callback.

await SDK.connect(`USERNAME`, `PASSWORD`);

Request Params#

Status	Description	Type	Required
`USERNAME`	Username	String	true
`PASSWORD`	Password	String	true

Response Params#

Arguments	Description	Type
statusCode	Status Code	Number
message	Success/Error Message	String

Make a voice call#

Initiate a call by providing the callee’s user JID into the makeVoiceCall method. Once the call initiated successfully, a callStatusListener callback will be triggered and callee user call status will be received here.

caution

If One to one call feature is unavailable for your plan, then it will throw 403 exception

note

To generate your own or others JID using the unique username got in registration response, use the const userJid = SDK.getJid(USER_ID) method.

SDK.makeVoiceCall(['USER_JID'], null, (success, error) => {
  if (error) {
    // Error occured while making the call
  }
  if (success) {
    // Call has been made successfully
  }
});

Request Params#

Param	Description	Type	Required
`USER_JID`	User JID	Array	true
`GROUP_ID`	Group Id - For one to one calls, provide `null`.	String	false
`callback`	Callback method to handle success and error while making the call	Method	false

success#

{
  statusCode: 200, // Number - status code
  message: "", // String - Success/Error Message 
  callType: "", // String - Call Type - "audio"
  roomId: "" // String - Unique room ID 
}

note

To receive the user track, a userTrackListener callback should already be registered in the caller's client app. Whenever you make the call to a user, you will receive your own track and the callee's track in the same callback method. To differentiate the user, You can use the 'localUser' and 'userJid' param. You will receive both Audio and Video track in the same callback method.

Sample Javascript code to play the track#

<html>
  <audio id="audio" autoplay playsinline></audio>
  <video id="video" autoplay playsinline></video>
  <script>
    //let track = TRACK_OBJECT from the callback method
    //let element = ELEMENT_OBJECT in which you need to play the audio/video
    let stream = new MediaStream([track]);
    try {
        element.srcObject = stream;
    } catch (e) {
        try {
          element.src = URL.createObjectURL(stream);
        } catch (e) {
          console.error("Error attaching stream to element", e);
      }
  }
  </script>
</html>

You need to supply the track object which was received in the callback method to the audio/video element based on the track type that you have received.

warning

For the Audio/Video call, you shouldn't play your own Audio track.

Receive incoming call#

To receive an incoming call, a incomingCallListener callback should already be registered in the callee’s client app. Whenever a user make call to a user, the callee user will receive the calling data in this callback.

// Callback Response Argument Structure
{
    allUsers:["USER1_JID", "USER2_JID",...],
    callTime: 1681905421215,
    callType: "audio|video",
    groupId: null|GROUP_ID,
    localUser: BOOLEAN,
    roomId: "wmupbheao",
    roomLink: "ndy-bmkb-eui"
    status: "calling",
    toUsers: ["USER_JID"],
    userDetails: {},
    userJid: "FROM_USER_JID",
    usersStatus: [{}]
}

Response Params#

Arguments	Description
allUsers	JID's of the users in the call.
callTime	Call intiated time in timestamp format.
callType	Describe the audio or video call.
groupId	Contain the group ID If the call is group call. Otherwise, the value will be NULL.
localUser	To determine local user or not
roomId	Call room ID.
roomLink	Call room Link.
status	Status of the call(calling, ringing, connecting, connected).
toUsers	Array of User JID of callee users.
userDetails	User details object of the callee users.
userJid	User JID who intiated the call
usersStatus	Array of users with the details of the call.

Answer a call#

To answer a call use the answerCall method.

SDK.answerCall((success, error) => {
  if (error) {
    // Error occured while answering the call
  }
  if (success) {
    // Call has been answered successfully
  }
});

note

To receive the user track, a userTrackListener callback should already be registered in the caller's client app. Whenever you answer the call, you will receive your own track and the caller's track in the same callback method itself. To differentiate the user, You can use the 'localUser' and 'userJid' param. You will receive both Audio and Video track in the same callback method.

Sample Javascript code to play the track#

<html>
  <audio id="audio" autoplay playsinline></audio>
  <video id="video" autoplay playsinline></video>
  <script>
    //let track = TRACK_OBJECT from the callback method
    //let element = ELEMENT_OBJECT in which you need to play the audio/video
    let stream = new MediaStream([track]);
    try {
        element.srcObject = stream;
    } catch (e) {
        try {
          element.src = URL.createObjectURL(stream);
        } catch (e) {
          console.error("Error attaching stream to element", e);
      }
  }
  </script>
</html>

You need to supply the track object which was received in the callback method to the audio/video element based on the track type that you have received.

warning

For the Audio/Video call, you shouldn't play your own Audio track.

End a call#

To end a call use the endCall method.

SDK.endCall((success, error) => {
  if (error) {
    // Error occured while ending the call
  }
  if (success) {
    // Call has been ended successfully
  }
});