JavaScript Sdk-API Usage guide

API Flow

Flow 1

Following flow chart describes the complete flow of setting up YuWee SDK

JavaScript Initial SetUp

Flow 2

Following flow chart describes the complete flow setting up and initiating a direct call

Start Call(JS)
Free Audio Video(JS)

Flow 2

Following flow chart describes the complete flow of receiving/answering a direct call

AnswerCall (JS)
Register Room (JS)

1. Setup Integration

1.1 Create an Application with YuWee

User can sign up and register their application on the YuWee-integrate home page via following link: https://www.yuwee.com On registering, the user needs to verify their account via email. Once email is verified, the user waits for a confirmation mail from YuWee. The confirmation email contains the “AppId” and “AppSecret” which would be needed to connect to YuWee servers via the SDK.

1.2 Setup and configure SDK

To use the YuWee Javascript SDK, the Application must include the following javascript files to their project: ● YuWee.js ● yConstants.js ● conferenceManager.js The SDK is basically a javascript library consisting of a set of APIs and callbacks. Most of these APIs are asynchronous and hence trigger callbacks on their completion. The SDK invokes the callbacks as a result of the events triggered by various actions such as ‘onIncomingCall’,’onCallRejected’, ‘onRemoteCallHangUp’, etc. These callbacks must be implemented by the application in order to handle necessary events.

1.3 Instantiation

Instantiate the SDK class “YuWee” to get access to all the APIs and callbacks

yuWee = new YuWee ( );

This creates an instance of the SDK Class, which is then used to perform all other operations.

1.4 Set event handlers

There are several callback events that needs to be handled in the application which aims to utilise the capabilities of YuWee SDK. Developer can assign their handler functions to these event hooks via setHandler method of YuWee in the following way:

var myHandlers = {
		'onAccountCreateSuccess' :  accountCreateSuccess,
    		'onAccountCreateFailure' :    accountCreateFailure,
    		'onSessionCreateSuccess' :  sessionCreateSuccess,
    		'onSessionCreateFailure'  :    sessionCreateFailure,
		'onAllUsersOffline': allUsersOffline,
		'onAllUsersBusy': allUsersBusy,
		'onReadyToInitiateCall': readyToInitiateCall,
		'onStreamRequestDowngrade':  streamRequestDowngraded,
		'onLocalStreamReceived' : gotLocalStream,
		'onIncomingCall' :  showIncomingCallNotification,
		'onInvitationExpired' :  invitationExpired,
		'onCallHangUpSuccess' :  callHangUpSuccess,
		'onInitiatorOffline' :  initiatorOffline,
		'onRemoteStreamReceived' :  gotRemoteStream,
		'onCallRejected' :  callRejected,
		'onCallAccepted' : callAccepted,
		'onRemoteCallHangUp' :  remoteUserHangUp,
    		'onCallEnded' :  callEnded,
    		'onInitialisationSuccess' :  initialisationSuccess,
    		'onVideoRoomRegistrationFailure' :  videoRoomRegistrationFailure,
    		'onIncomingCallWhileBusy':  handleIncomingCallWhileBusy,
    		'onCallRespondedFromOtherLogin' : handleCallResponded,
    		'onBrowserIncompatible' :  handleBrowserIncompatibility,
    	              'onVideoToggle' :  handleVideoToggle,
    	           'onAudioToggle' :  handleAudioToggle,
    	            'onRemoteVideoToggle' :  handleRemoteVideoToggle,
    	            'onRemoteAudioToggle' :  handleRemoteAudioToggle,
    	            'onScreenSharingError' :  handleScreenSharingError,
    	            'onScreenShareStatusChanged' :  screenShareStatusChanged,
    	            'onNewMemberAddedToCall' :  newMemberAddedToCall
		};
	    yuWee.setHandlers(myHandlers);

Above code snippet defines various event handlers and registers them to the respective hook that is fired from within SDK. Whenever an event occurs within the library, the respective handler is called. In above code snippet, the left side contains the event name and the right side depicts the name of the handler function that binds to the event.

1.5 Set application credentials

yuWee.setAppCredentials(appId, appSecret);
  • Description & Usage This API is used to set the Application credentials received after registering the application with YuWee in step 1.1 . These credentials are used for the authentication purpose.
  • Parameters
Parameter Name
Type
Mandatory
AppId String Yes
AppSecret String Yes

1.6 Create/Register user

yuWee.createUser(name, email, password)
  • Description & Usage This API is used to signup a new user in YuWee.
  • Parameters

 

 

Parameter Name
Type
Mandatory
Description
name String Yes 3-30 chars limit
email String Yes Requires a valid email
password String Yes 6-20 chars limit
  • Call-back Events:
Event name
Response data
Description
onAccountCreateSuccess Success message This event is called when an account has been successfully created in YuWee
onAccountCreateFailure Error message This event is called when account creation fails for some reason

Note

For more security, These APIs can be called from server side as well. API to export the user list via CSV is also available for initial migration. Please request for “Server-side API” document for the same.

1.7 Create session via credentials

yuWee.createSessionViaCredentials(email, password)
  • Description & Usage This API will create a new session for the user.
  • Parameters
Parameter Name
Type
Mandatory
Description
email String Yes Valid email
password String Yes 6-20 chars limit
  • Call-back Events:
Event name
Response data
Description
onSessionCreateSuccess Success message, userinfo (user details and Access Token) This even is called when a session has been successfully created. The Callback handler will receive user information and access token to be used for other APIs authentication
onSessionCreateFailure Error message This even is called when session creation fails for some reason
  •  Create Session Via Email Token
yuWee.createSessionViaToken ( inviteToken )

Description & Usage This API is used to create session for a Callee who has responded to a call (accept/reject) via email. This scenario will be further revisited and explained in 4.1

Parameters

 

Parameter name
Response data
Description
inviteToken String Encrypted token with user info, call info and access token
  • Call-back Events:
Event name
Response data
Description
onInvitationExpired nil This event is fired when the call has already ended. A call is considered to be ended when at least one of the member has ended the call and no one is left in the room
onSessionCreateSuccess Success message, userinfo (user details, call details and access token) This even is called when a session has been successfully created. The Callback handler will receive user information, call information and access token to to be used for other APIs authentication and call setup
onSessionCreateFailure Error message This event is called when session creation fails for some reason
  • Initialise Session
yuWee.init ( yuWeeInitParam )
  • Description & Usage This is the last step for setup. In this initialisation step, user’s information and authorisation token received from 1.7 or 1.8 needs to be passed to the YuWee library for internal API calls. When User logs in via createSessionByCredentials or createSessionByToken, these APIs provide “userInfo” that we need to initialise YuWee:
yuWeeInitParam.user = userInfo.user;
yuWeeInitParam.authToken = userInfo.auth_token;
yuWee.init(yuWeeInitParam);
  • Call-back Events
Event name
Response data
Description
onInitialisationSuccess nil This event is triggered when the session has been successfully initialised

2. Start a call

  •  Setup Call
yuWee.setupCall(callParams)
  • Description & Usage This API is used to setup a call. It takes a JSON parameter in the following format:

callParams = {isGroup: false, inviteeEmail: <email of Callee>, inviteeName: <name of callee>, invitationMessage: <message in string>, callType: <audio/video> };

e.g.

callParams = {
isGroup: false, inviteeEmail: “ronny@yuwee.flywheelsites.com, inviteeName: “Ronny”, invitationMessage: “Hi Ronny, Lets have a call”, callType: “video” }; yuWee.setupCall(callParams);
  • Call-back Events
Event name
Response data
Description
onBrowserIncompatible nilm This event is triggered when caller’s browser is incompatible and doesn’t support YuWee. For details on the supported OS and browsers check the functional documentation of YuWee-integrate
onAllUsersOffline nil This event is triggered if none of the callees is online. In this case, a mail is triggered for the callees with links to join the call. The callee can click on the email link so as to re-initiate the call to the caller. The caller gets a call notification in its screen if he is not ready on the call.
onAllUsersBusy nil This event is triggered in case all the Callees are busy on another call and hence unavailable
onReadyToInitiateCall nil The event is triggered when at least one callee is online and available. By now the available callees have already received a call notification via a callback. At this point, the caller can be taken to the next step of call connection
  • Capture Local Stream
yuWee.getMediaStream(callType)
  • Description & Usage This method will initialise and start capturing media (Audio/Video) from the media device (webcam and/or Mic).
  • Call-back Events:
Event name
Response data
Description
onLocalStreamReceived localStream This event is called when a session has been successfully created. The call-back handler will receive user information and accesss token to be used for other APIs authentication
onStreamRequestDowngrade Downgrade Message

By default the video stream captured is of HD quality. In case of incompatible hardware, one or many of the following can happen: 1. If webcam is non-HD, this event is received and the request automatically fall backs to normal SD type. If SD stream is successfully captured “onLocalStreamReceived” event is fired which receives the SD stream(video+audio) as a parameter

2. If webcam is missing, this event is fired and the request fallbacks to an “Audio-only” call. If audio-stream is successfully captured, “onLocalStreamReceived” is fired which received the Audio-stream as the parameter.

3. If both WebCam and microphone are missing, “onStreamCaptureFailure” is called. The call can be terminated on receiving this event.

onStreamCaptureFailure Error message This event is called when stream capture fails for some hardware compatibility issues
  • Manage Local Stream
yuWee.attachMediaStream(stream)
  • Description & Usage Now, the stream received in the callback handler in 2.2 needs to be rendered to an HTML Video or Audio element. This API facilitates the same
gotLocalStream = function(myStream){
var bigVideo = document.querySelector('#bigVideo');
                        yuWee.attachMediaStream(bigVideo,myStream);
}

3. Answer a call- I (Direct call)

  • Respond to Incoming Call
  • Whenever there is an incoming call, ‘onIncomingCall’ event is triggered at the callee’s end. In the handler of this event, user can perform following 2 actions:(i) Option 1 – Accept A Call

(i)  Option 1 – Accept A Call

  • Description & Usage:
yuWee.registerInVideoRoom(stream)

Callee can accept the call and join the room using above API. Once accepted, a connection is established via YuWee servers and both the caller and callee will start receiving the streams of each other if its a 1-to-1 call, or a mixed stream if it is a group call. The received remote stream can be attached to the main Video element via attachMediaStream as discussed earlier. The local stream can be attached to a smaller video element.

gotRemoteStream = function(remoteStream){
	var bigVideo = document.querySelector('#bigVideo');
	var smallVideo = document.querySelector('#smallVideo');
	yuWee.attachMediaStream(bigVideo, remoteStream);
	yuWee.attachMediaStream(smallVideo, localStream);
}
  •  Call-back Events:
Event name
Response data
Description
onVideoRoomRegisterationFailure Error message This event is called at caller’s side, when a callee has accepted the call via above API
onRemoteStreamReceived Remote stream Once a connection has been established, this event is fired to each user and they will receive the remote stream as a callBack parameter of this event

(ii)  Option 2 – Reject A Call

yuWee.rejectIncomingCall()

Callee can reject an incoming call using above API

  •  Call-back Events:
Event name
Response data
Description
onCallRejected userId of rejector This event is called once the call is rejected by any of the callee. userId of the rejector is received as the call back parameter. The caller can choose to drop the call and redirect to dashboard if needed.

4. Answer a call- II (via email)

When a Callee clicks on an email call invite which contains the encrypted token having the required user, call information and authorisation token embedded, following thing happens in sequence:

  • Callee is supposed to be taken to the dashboard of the web application.
  • Since dashboard is common for direct caller, callee or email callee, we need to have a check if the flow needed is for an email call or not. The same can be done via following API. It checks the url to detect the same.
yuWee.checkIfCallViaEmailInvite(url)
  • Parameters
Parameter name
Type
Description
url String This url can either be the dashboard url if its a direct incoming call, or the url of the email invite sent to callee via email. We have to check for the later, to decide the flow
  • Return

 

Key name
Type
Description
inInvite boolean true: url corresponds to the call accepted invite email. false: url doesn’t correspond to call accepted via invite email
inviteToken string This is an encrypted token, containing userinfo of self, callinfo and accessToken. These values are deciphered from the encrypted string via another API described below: createSessionViaToken()

Once inviteToken is received and a Session has been created via createSessionViaToken(), and if the the callee joining via email is the first user to join the call, i.e. the call hasn’t started yet, other participants will get a “onIncomingCall” event to join the call. In other case if the call in ongoing, the callee will simply join it. In both the case, the callee follows the flow described in . All the concerned API have already been covered earlier.

5. Call add-on features

There are several add-on YuWee features that can be leveraged in the form of APIs to enhance user experience. They are described below:

  • Pause/Un-Pause Video Stream
yuWee.toggleVideoPause ()

A call participant can choose whether he wants his video stream to be shown to other participants or not. This can be done by toggling the Video stream to pause or unpause via this API. For a Video Call, Video stream is by default in unpaused state, whereas in Audio call, It is in paused state. Calling the API will toggle the state.

  • Call-back Events:
Event name
Response data
Description
onVideoToggle isVideoPaused(boolean) This event is received when participant’s own video has been toggled successfully. Video stream state is also received as callback parameter
onRemoteVideoToggle {isVideoPaused(boolean),email(String)} This event is received when some other participant has toggled his video stream. Video stream state and the email of the participant is also received as callback parameter
  • Mute/Unmute Audio Stream
yuWee.toggleAudioMute ()

A call participant can choose whether he wants to share his audio stream with other participants or not. This can be done by toggling the Audio stream to mute or unmute state via this API. For bothAudio and Video Call, Audio stream is by default in unpaused state. Calling the API will toggle the state.

  • Call-back Events:
Event name
Response data
Description
onAudioToggle isAudioMuted(boolean) This event is received when participant’s own audio stream has been toggled successfully. Audio stream state is also received as callback parameter
onRemoteAudioToggle {isAudioMuted(boolean), email(string)} This event is received when some other participant has toggled his audio stream. Audio stream state and the email of the participant is also received as callback parameter
  • Add participants to an Exisiting Call
yuWee.addParticipantsToCall ()
  • Parameters
Parameter name
Type
Description
newParticipants Array of emails Array of email of all the users being added to the call
groupName String This is to provide a group name in case adding participant to a 1-to-1 call
  • Callback events

 

Event name
Response data
Description
onNewMemberAddedToCall Array of userInfo with id, name and email This event is received by all the existing participants in a call when new participants are added via above API

6. Screen Sharing

yuWee.toggleScreenShare( )

User can share their screen during a call via this API. Currently this feature is supported only for Web Chrome and Web Mozilla. While Screen sharing feature works by default in Mozilla, a chrome-extension plugin is needed for Chrome.

..note:: Providing the Chrome extension along with code-base is in the scope of YuWee.

  • Callback events

 

Event name
Response data
Description
onScreenSharingError Error message This event is received when there occurs an error while initiating screen share. Screen share usually fails because of one of the following reasons: 1. Incompatible browser 2. Screen sharing cancelled from the confirmation window of chrome extension 3. Chrome plugin missing
onScreenShareStatusChanged statusId, stream

This event is triggered whenever the status of screen sharing lifecycle changes. Screen sharing feature has 3 different states:

0- inactive: When this event is triggered with status=0, it depicts that screen sharing has been deactivated

1- active: When this event is triggered with status=1, it depicts that screen screen share is active. Local screen stream is received as a callback. The same can be attached to a HTML element as described earlier. Others users start receiving your screen stream

2- deactivating: When this event is triggered with status=2, it depicts that screen share is being deactivated as a callback. The same can be attached back to the HTML element

  • Callback events
Event name
Response data
Description
onIncomingCallWhileBusy Call information in JSON This event is received when a user receives a new call notification while he is already busy in one
onCallRespondedFromOtherLogin nil  This event is received when the user is logged-in at multiple devicesand has responded(accepted/rejected) from the other device. All other login platforms will receive this event. Developer may chose to drop the incoming call notification listening to this event, showing a missed call

7. Call hangup

yuWee.hangupCall ( callEndType )

User can share their screen during a call via this API. Currently this feature is supported only for Web Chrome and Web Mozilla. While Screen sharing feature works by default in Mozilla, a chrome-extension plugin is needed for Chrome.

..note:: Providing the Chrome extension along with code-base is in the scope of YuWee.

  •  Parameters

 

Parameter name
Type
Description
callEndType String “end&notify”-> if a call is hung with this parameter, notification is sent to all other

participants via event “onRemoteCallHangUp”

“end”-> if a call is hung with this parameter, no notification is sent to other participants of the call

  • Callback events

 

Event name
Response data
Description
onCallHangUpSuccess nil This event is received by a participant when it has successfully ended the call
onRemoteCallHangUp Remote user info{userinfo, name, email} This event is received by a participant of a call, when some other participant has ended/left the call
onCallEnded nil This event is called when a call has ended, i.e all the participantshave left it successfully

8. Schedule a meeting

yuWee.scheduleMeeting ( callParamsObj )

This API is used to schedule a call for a future date-time. Once a call has been scheduled, a meeting setup mail is sent to each participant with the meeting information. The email automatically makes entry to the respective email client calendar for native client reminder for the meeting. E.f. if the mail goes to outlook, an event is entered to the outlook calendar. Other supported clients/Calendars are Gmail, Apple calendar. User can accept/reject the meeting via calendar.

  •  Parameters

 

Parameter name
Type
Description
scheduler_name String Name of the meeting
scheduler_description String Meeting description
date_of_start String Format dd/mm/yyyy, eg 17/Aug/2019
time String Format HH:MM
duration String Format HH:MM
scheduler_media String “audio”/”video
time_zone String Format: “GMT+HH:MM” e.g GMT+05:30
alert_before_meeting number In minutes
members Array Array of emails
  • Callback events
Event name
Response data
Description
onMeetingCreatedSuccessfully Meeting details This event is received by each participant once a meeting has been successfully registered
onMeetingCreationFailure Error message This event is fired when a meeting creation fails
onMeetingReminder Meeting details This event is received by each participants just before the reminder duration prior to the scheduled time
onMeetingExpired Meeting details This event is received by each participant once a meeting has expired
onMeetingDeleted Meeting details This event is received by each participant once a meeting has been been deleted by the host