JavaScript Calls
This page lists the JavaScript calls that are available through the Screenleap API. To integrate, add the following snippet of code to the page that will be used to start the screen share right before the closing body tag:
- Start a Screen Share
- Controlling an Active Screen Share
- Implementing Callback Functions
- Access Screen Share Properties
- Installing the Browser Extension
Start a Screen Share
After you have created a screen share session (see Make a Screen Share Request), these functions can be used to start the screen share.
screenleap.startSharing(presenterAppType, screenShareData, callbacks)
Starts a screen share using the specified presenter app.
The available presenterAppType
options are:
- NATIVE - The native Screenleap application for Mac and Windows. The native application has the advantage of only requiring a download the first time it is run, or when an update is required.
- IN_BROWSER - The Screenleap browser extensions allows your users to share their screens by only installing a browser extension. Only available for Chrome. The recommended option for presenters on Linux.
- DEFAULT Deprecated - If the user is on a Mac or Windows machine, this option will launch the appropriate native app.
The screenShareData
is the JSON object received from a successful request to make
a new screen share.
The callbacks
is a JavaScript object contain functions
that you implement that will be called when specific screen share events occur during the course of a screen share.
The available callbacks are:
nativeDownloadStarting
- ForNATIVE
shares, this callback will be called when the download of the native app begins. Use this callback to show instructions to the users for installing the app and starting the screen share.screenShareStarting
- For all shares, this callback will be called when the downloaded app starts. Use it to display feedback to the user that the share is starting.appConnectionFailed
- This callback will be called when the page containing the screenleap.js file is not able to connect with the app server. Use this callback to ask the user to check his/her Internet connection.screenShareStartError
- This callback will be called when the screen share cannot be started. Use this callback to let the user know that the screen share was unable to be started and allow them to try starting a new share.
screenleap.downloadNativeApp(onAppDownloadEnd, callbacks)
Downloads the native app and calls the onAppDownloadEnd
function when the download is complete.
Accepted callback:
nativeDownloadStarting
: function to call before the download begins. Use this call to display the installation instructions.
screenleap.startAppUsingCustomProtocolHandler()
Attempts to start the native app using the custom protocol handler. This call is usually made from a link in the instructions shown the users when the automatic attempt to start the presenter app using the custom protocol handler fails.
Controlling an Active Screen Share
screenleap.stopSharing()
- Stop the active screen share.screenleap.pauseSharing(successCallback, errorCallback)
- Pause the active screen share.screenleap.resumeSharing(successCallback, errorCallback)
- Resume a paused but active screen share.
ImplementingCallback Functions
You can get notified about various screen sharing events by implementing JavaScript callback functions on the screenleap object. For example, you can get notified when a viewer joins or leaves a screen share so that you can update your page to show or hide participant information.
screenleap.onScreenShareStart()
- This function is called when the web page is able to successfully connect to the presenter app. If you do not define this function, the default behavior is to pop up an alert.
screenleap.onPresenterConnect()
- This function is called when the presenter app has successfully connected to the app server.
screenleap.onPresenterConnect
usually gets called afterscreenleap.onScreenShareStart
but this is not guaranteed. Most of the time, you can implement either callbacks to add code you want to run after the screen share starts. Some Screenleap JavaScript calls (such asscreenleap.startRecording
andscreenleap.stopRecording
) only works after the presenter app has connected to the app server, so you'll want to use thescreenleap.onPresenterConnect
callback for these situations. screenleap.onScreenShareEnd()
- This function is called when a screen share ends. If you do not define this function, the default behavior is to pop up an alert.
screenleap.onViewerConnect(participantId, externalId)
screenleap.onViewerDisconnect(participantId, externalId)
- These functions are called whenever a viewer joins or leaves a screen share, respectively. The
participantId
is a Screenleap identifier for a participant. TheexternalId
parameter will only be included if you provided an optionalexternalId
for this viewer's connection.
Note that this information is provided in order to give the presenter real-time information about viewer presence. It is not intended to be used for billing purposes. If a viewer's Internet connection drops and reconnects repeatedly, each event will trigger a callback. Please make use of thecallbackOnEndUrl
callback to receive billing information for a completed screen share. screenleap.onPause()
screenleap.onResume()
- These functions wil get called when the screen share gets paused or resumed, respectively.
screenleap.onRecordStartError
- This function is called when we are unable to start recording the screen share due to an error. When calling
screenleap.startRecording
, iferrorCallback
is passed in, errors starting the recording will be passed to the callback. Otherwise, errors starting the recording will be reported viascreenleap.onRecordStartError
. Even if you passerrorCallback
toscreenleap.startRecording
, you should still implementscreenleap.onRecordStartError
so you get notified when recording couldn't be started whenautoRecord
is enabled. screenleap.error(action, message, err)
- This function is called when an error is encountered. The
action
is the name of the action that triggered the error. Themessage
may provide some additional explanation of the issue. Theerr
is either anError
object or anXmlHttpRequest
object, depending on the type of error. The default behavior is to pop up an alert to help with integration. You will want to override this before releasing to your users so that your users are not shown an alert everytime there is an error.
Important Note: These functions are defined on the screenleap object which is instantiated by screenleap.js
.
As a result, it is important that you implement these callbacks in window.onload
to ensure that the screenleap
object is instantiated first.
Sample Callback Implementation
Access Screen Share Properties
screenleap.getScreenShareCode()
- returns the 9-digit share code for this screen share.screenleap.getViewerUrl()
- returns the URL for viewing this share.
Installing the Browser Extension
screenleap.isBrowserSupportedForExtension()
- Returnstrue
if the user's browser is supported for Screenleap browser extensions.screenleap.checkIsExtensionInstalled(yesCallback, noCallback)
- Checks whether the Screenleap browser extension is installed, then calls the appropriate callback function.screenleap.checkIsExtensionEnabled(yesCallback, noCallback)
- For Chrome only, checks whether the extension is enabled, then calls the appropriate callback function.screenleap.installExtension(successCallback, errorCallback, redirectUrl)
- Installs the Screenleap extension, if it is not already installed, then calls the appropriate callback function. The Chrome installation will require a temporary redirect to ascreenleap.com
page. By default, the page is automatically redirected back to the originating URL on completion of the installation. To override this behavior, you may provide an alternateredirectUrl
to which the user will be redirected after the installation completes.