Presenter Integration

The first step for adding screen sharing to your website is to integrate the presenter app so that your users can share their screen.

Integrating the presenter app consists of the following steps:

Want to dive right in? Please check out our reference integration for a working example that you can use as the basis for your own integration.

1. Link to screenleap.js From Your Website

2. Make a Share Session Request

Make this call to create a share session on the Screenleap server. The request will return a screenShareData JSON object that you can use to start the presenter app.

Request

POST	https://api.screenleap.com/v2/screen-shares
HEADERS	authtoken:<authtoken>

Sample Request

curl -H "accountid:<accountid>" -H "authtoken:<authtoken>" -X POST https://api.screenleap.com/v2/screen-shares

import java.io.BufferedReader; import java.io.InputStreamReader; import java.net.HttpURLConnection; import java.net.URL; import org.json.JSONObject; URL url = new URL("https://api.screenleap.com/v2/screen-shares"); HttpURLConnection conn = (HttpURLConnection) url.openConnection(); conn.setRequestMethod("POST"); conn.setRequestProperty("accountid", "<accountid>"); conn.setRequestProperty("authtoken", "<authtoken>"); conn.connect(); BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream())); StringBuilder buf = new StringBuilder(); String line; while ((line = rd.readLine()) != null) buf.append(line); rd.close(); JSONObject screenShareData = new JSONObject(buf.toString());

$url = 'https://api.screenleap.com/v2/screen-shares'; $ch = curl_init($url); curl_setopt($ch, CURLOPT_POST, 1); curl_setopt($ch, CURLOPT_HTTPHEADER, array('authtoken:<authtoken>')); curl_setopt($ch, CURLOPT_POSTFIELDS, 'accountid=<accountid>'); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Whether you need the following line depends on your curl configuration. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); $screenShareData = curl_exec($ch); curl_close($ch);

import simplejson import urllib2 headers = {'accountid': '<accountid>', 'authtoken': '<authtoken>'} req = urllib2.Request('https://api.screenleap.com/v2/screen-shares', data={}, headers=headers) res = urllib2.urlopen(req) screenShareData = simplejson.loads(res.read())

require 'json' require 'net/http' require 'uri' uri = URI.parse('https://api.screenleap.com/v2/screen-shares') req = Net::HTTP::Post.new(uri.path, initheader = {'accountid' => '<accountid>', 'authtoken' => '<authtoken>'}) http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true res = http.request(req) screenShareData = JSON.parse(res.body)

Presenter Options

You can configure the share session and the presenter app by adding query parameters to the request URL. See the complete list of presenter options.

IMPORTANT: One parameter that you need to be sure to include for your share sessions to work optimally is either the presenterIpAddress or the presenterCountryCode parameter. We need at least one of those parameters in order to properly route your share sessions to the closest app servers.

The API demo page allows you to play around with the various presenter options and see how they affect the share sessions and presenter apps. Click the Show presenter options link on the demo page to see the list of presenter options that you can customize. Once you have found a configuration that you are happy with, you can copy the query parameters that gets generated and use it to customize your share session requests.

Response

A successful request will return a response with 200 status code and a JSON object. You will pass this JSON object to the screenleap.startSharing call to start the presenter app. The JSON object also includes a viewerUrl that you will be used for integrating the viewer.

See Error Responses for information on how to handle a failed request.

3. Launch the Presenter App

To launch the share session, include the screenleap.js JavaScript file in your web page and call screenleap.startSharing(presenterAppType, screenShareData, callbacks).

The presenterAppType specifies the Screenleap presenter apps to use for the share. Allowed values are:

IFREE - Installation-free sharing. Neither the presenters nor viewers need to install any software.
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.

The screenShareData is the JSON object received from a successful new share session request.

The callbacks is a JavaScript object containing functions that gets called during the course of a share session. By implementing the callbacks, you can be notified of share session events so that you can take the appropriate action (such as showing instructions to your users or updating your application to match the state of the share session). See the list of available callbacks.

4. Implement Callback Handlers

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 share session 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 after screenleap.onScreenShareStart but this is not guaranteed. Most of the time, you can implement either callbacks to add code you want to run after the share session starts. Some Screenleap JavaScript calls (such as screenleap.startRecording and screenleap.stopRecording) only works after the presenter app has connected to the app server, so you'll want to use the screenleap.onPresenterConnect callback for these situations.
screenleap.onScreenShareEnd(): This function is called when a share session 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 share session, respectively. The participantId is a Screenleap identifier for a participant. The externalId parameter will only be included if you provided an optional externalId 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 the callbackOnEndUrl callback to receive billing information for a completed share session.
screenleap.onPause() screenleap.onResume(): These functions will get called when the share session gets paused or resumed, respectively.
screenleap.onRecordStartError: This function is called when we are unable to start recording the share session due to an error. When calling screenleap.startRecording, if errorCallback is passed in, errors starting the recording will be passed to the callback. Otherwise, errors starting the recording will be reported via screenleap.onRecordStartError. Even if you pass errorCallback to screenleap.startRecording, you should still implement screenleap.onRecordStartError so you get notified when recording couldn't be started when autoRecord 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. The message may provide some additional explanation of the issue. The err is either an Error object or an XmlHttpRequest 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

5. Add UI-Specific Integrations

Below are additional UI-specific integrations that you need to perform to complete the integration and ensure that your implementation works seamlessly for your users.

Native Apps

We use a custom protocol handler to start the native presenter app from the web browser. The following additional steps are required if you will be using native apps in your integration:

If you have onbeforeunload/onunload handlers defined, you need to unbind them before starting a share session. A call to the custom protocol will trigger this event and result in unexpected behavior. You can rebind them after the share is running.
If you have not already done so, implement the onScreenShareStartError() callback function. The callback should show a dialog with a link to retry the app download and another link to retry the custom protocol handler. See screenleapRetryNativeInstallationInstructions in the source code of the API demo page for an example.
function onScreenShareStartError() { // Show instructions similar to the contents of the // screenleapRetryNativeInstallationInstructions div on the API demo page. // You can add a setTimeout() call here if you would like to give the user // more time to run the downloaded presenter app before showing the // instructions. }
Update the screenleap.startSharing(…) function to pass in the onScreenShareStartError callback using the screenShareStartError key.
screenleap.startSharing('NATIVE', screenShareData, {screenShareStartError: onScreenShareStartError});
When the retry download link in the instructions is clicked, it should call screenleap.downloadAndStartNativeApp() to initiate the download of the presenter app. The call will also attempt to start the presenter app using the custom protocol handler after a delay (to give the user time to install the presenter app).
There are situations in which the presenter app may not be installed before the automatic attempt to the presenter app. In these instances, the users will need to manually click on the custom protocol handler link after installing the presenter app to start it. When clicked, the link should call screenleap.startAppUsingCustomProtocolHandler().

First-time users will be prompted to confirm that they want to launch the presenter app using the custom protocol handler.

Implementation Notes

Due to browser limitations, it is not possible to determine if a user has successfully installed the presenter app or given permission to use the custom protocol handler. As a result, you will need to provide your users with a manual way of a) downloading the presenter app and b) starting the presenter app using the custom protocol handler. Our testing on the Screenleap site has shown that the instructions with the retry links results in the best user experience and ensures that users don’t get stuck in a dead-end during the start process.

The download link is necessary to address situations where the user has installed and subsequently deleted the presenter app. We place a cookie on the user's browser after the user has successfully installed the presenter app and started a share session. On subsequent share session attempts, we do not attempt to automatically download the presenter app. Without the download link, the user who deleted the presenter app without also deleting the browser cookie would be stuck at a dead-end.

The custom protocol handler link can be necessary to allow the user to start the share session. If the presenter app is not installed before the automatic attempt to start the presenter app, the user will need to use the custom protocol handler link to manually start the share session after the app installation.

The above issues only affect the initial installation of the presenter app. Once the user has installed the presenter app and granted permission to use the custom protocol handler, subsequent share sessions will start quickly and without requiring any additional user interaction.

Continue to Viewer Integration »