API (Native)

Viewer Integration

When you make a request to start a new share session, the JSON content that you receive will contain a viewerUrl. You can integrate the viewer by either redirecting the user to the viewerUrl or embedding the viewerUrl into an iframe.

Request

The viewer can be customized by adding optional query string parameters to the viewerUrl:

fitToWindow By default, the share session renders for the viewer at the actual size to ensure the highest quality image. To resize the share session to fit within the user's browser display area, set this option to true.
showStop If this parameter is set to true, a bar will display at the top of the viewer with a stop button. The default setting is false.
showResize If this parameter is set to true, a bar will display at the top of the viewer with a drop-down menu. The user can use this menu to toggle the view between "Fit to window" and "Actual screen size". The default setting is false.
externalId You may now pass in an external ID of up to 192 characters to save with the viewer data in a share session. This can be useful for connecting share session viewer connections to records on your system.
WARNING: If passed in, the external ID needs to be unique for each viewer in a share session. Assigning the same external ID to multiple viewers in a share session will break viewing for the share session.
redirectOnError* A URL to which the user should be redirected if there is an error. If omitted, an error message is displayed.
redirectOnEnd* A URL to which the user should be redirected when the share session ends. If omitted, a message is displayed to inform the user that the share session has ended.
language The code of the language in which to translate viewer messages. By default, Screenleap will attempt to pick up the correct language from the "Accept-language" HTTP header. The currently available languages are listed below. To request a language not already on the list, please contact support.
  • en: English
  • nl: Dutch

* Note: Redirects will not work in an iframe; this option would need to be used for a full-window viewer.

Viewer Notifications

If you are embedding the viewer page in an iframe, you can get notified of share session events from the viewer page by adding a listener to your page:

  • SCREEN_SHARE_ENDED - Sent by the viewer page when the share session has ended.
  • VIEWPORT_SIZE - Sent by the viewer page when the viewport size has changed. In order to receive this message, you must first notify the viewer page that you are interested in listening for the event.
  • SLOW_CONNECTION - Sent by the viewer page when we detect that the viewer has a slow Internet connection so you can let them know that their share session may experience additional lag.

To get alerted about changes to the viewport size (which is useful if you want to change the layout of your page in response to changes in the aspect ratio of the shared screen), you would need to make the following call:

document.getElementById('iframeId') .contentWindow.postMessage('{"on":"VIEWPORT_SIZE"}', '*');
window.addEventListener('message', function(e) { if (e.data == 'SCREEN_SHARED_ENDED') { // The screenshare ended on the viewer side. } else if (e.data.indexOf('VIEWPORT_SIZE') != -1) { var data = JSON.parse(e.data); if (data.value) { console.log('new viewport size: ' + data.value.width + 'x' + data.value.height); } } else if (e.data.indexOf('SLOW_CONNECTION') != -1) { console.log('Viewer appears to have a weak Internet connection.'); } });

Embedding Viewer In IFrame

If you want to embed the viewer page in an iframe, it is possible to configure the dimensions of the viewer page to match the dimensions of the iframe so that no scroll bars are shown:

  • Create an iframe element with the viewerUrl as the source. Add "overflow:hidden" as the style. Make sure the width and height attribute are set to your desired values. Add an onload with "setViewerDimensions(this)" as the value.
    <iframe id="viewerFrame" width="1000" height="600" src="viewerUrl" style="overflow:hidden" onload="setViewerDimensions(this)"></iframe>
  • Add the following to the page containing your iframe:
    <script> function setViewerDimensions(iframe) { iframe.contentWindow.postMessage('{"width":' + iframe.width + ', "height":' + iframe.height + '}', '*'); } </script>

Viewer Customization Wizard

The API demo lets you try out each of the customization options above. We recommend that you click Show viewer options on the demo page and use it to find the configuration that works best for you. Once you have it configured, you can copy the URL from that page to use in configuring your share session.

Continue to Recording »
/api/v2/viewer
OK
OK
OK
...