Screen Recorder Launcher API Functions

Use the Screen Recorder Launcher API to create a global SOMLauncher javascript object. This object exposes the functions contained in this article.

First you'll need to download and host the API javascript file, jar files, and install executables that we provide.

These files can be hosted anywhere on your servers but for the purchase of this article we'll assume they are all uploaded to a folder on your server accessible at https://myhost/SOM

To start using the API, include the following javascript file: 

<script type="text/javascript" src="https://myhost/SOM/som-launcher-2.0.X.js"></script>

The launch function takes a number of options detailed below.  Most implementations will use the Basic Uploader which will require options also detailed in the  Configuring the Basic Uploader .   If you are developing a custom user interface (UI) or custom upload endpoint, such as to your backend or a cloud service not supported in the Basic Uploader, then you can go to Configuring the Custom Uploader . 

Table of Contents

• SOMLauncher.launch()
  
• SOMLauncher.setMarkInstall()
  

SOMLauncher.launch()

Several options can be passed through the function named SOMLauncher.launch( options ) .

Required Properties

When using the SOMLauncher.launch() function, set the following properties:

• Partner Information
  
• jarHostPath
  
• Jar File Names
  
• Callback Function
  

PARTNER INFORMATION

To implement your integration, make sure to set the partner information in the JavaScript. Contact your account manager at Screencast-O-Matic to obtain your partner information. 

Specify the partner information when adding API code to your website.

JARHOSTPATH

This property provides the URL path where the jars and zip files are hosted on your system for download by the user (replace any spaces in your path with %20).

jarHostPath: 'https://myhost/SOM/',

JAR FILE NAMES (PROVIDED BY SOM)

All jars must be signed by the same certificate.

jars: {

   all : [
   // Jars that are loaded for both Windows and Mac OSX
   ],
   win : [
   // Jars that are only loaded on Windows
   ],
   mac : [
   // Jars that are only loaded on Mac
   ]
   },

CALLBACK: FUNCTION (RESULT)

This required function is called back with result of the launch attempt.

callback: function(result)

The returned value is an object with the following result.* properties. 

Value 

Description 
string 
If result.type == 'success' , then this is the string for the launch type used ("java" or "protocol") 

result.protocolNoInstallMarked: (true or undefined)

result.protocolInstalled: (true, false, or undefined)

In browsers for Win8+IE10+ and Firefox, detection of an installed custom protocol is available. If the current browser has the detection feature, this value is set to true or false depending on if the custom protocol is installed. If the browser doesn't support the detection then this will be undefined.

result.protocolUserCancelled: (true, false, or undefined)

In browsers for Win8+IE10+, detection of a user clicking cancel (rejecting) the custom protocol is available. If the current browser has this feature, this value is set to true or false depending on the user response to the prompt (to run the custom protocol or not). If the browser doesn't support the detection, then this value will be undefined. 

result.unsupportedType: (string)

result.error: (string)

If there is an error while launching, this value is set to a string that you can use to help debug. Only valid when using the optional remoteStatusService .

Optional Properties

When using the SOMLauncher.launch() function, the following optional properties can be set:

• order
  
• timeout
  
• checkInstallMark
  
• remoteStatusService
  
• properties
  

order (Launching options)

The launching options and order they should be tried for Windows or mac. The defaults shown below default to not trying java in Chrome (Chrome does not support Java any more). The launcher script remembers if a method had previous success and attempts to launch that first upon subsequent launches. For example, using the default values below, if the "protocol" method worked on the previous attempt, then the script will try that first instead of trying "java" first.

order: { win: isChrome ? ['protocol'] : ['protocol','java'], mac: ['protocol'] },

timeout

The optional timeout in seconds that causes the code to wait before designating that a particular launch option failed. You can also set up a different timeout to use if the launch type has previously succeeded on this computer, so you can wait longer for it to work using the protocolAfterSuccess and javaAfterSuccess timeouts. The default values are:

timeouts: 
   { 
   protocol: 10, 
   java: 10, 
   protocolAfterSuccess: 10, 
   javaAfterSuccess: 10 
   }

checkInstallMark

Set this optional property to true if the script should only try protocol launcher if it finds that the install was attempted from this browser.

checkInstallMark: false, 

remoteStatusService

The JavaScript polls localhost ports looking for the recorder to start. If you are using https, this may cause warnings in the browser console (browser dependent). The warnings include insecure access. To remove these warnings, create a remote service on your servers that the JavaScript will poll and the recorder will notify when it has been started. The service requires two end points. One that the recorder notifies, which is the updateStatus URL, and a second that the JavaScript polls, which is the pollStatus URL.

updateStatus

The updateStatus is a URL that the recorder will POST to upon startup to report the status for this launch. The POST body will be JSON like:

{ "status":"STATUS" } 

pollStatus

The pollStatus is a URL that the JavaScript uses to (long) poll for the status update. The result of the GET request should be JSON like:

{ "status":"STATUS", "pollingInterval":5 } 

If no status is reported yet, then the STATUS would be an empty string. Else, it should be the status string reported in the updateStatus call. The pollingInterval is an optional timeout (in seconds) that the JavaScript uses when calling the server (default value of 5 seconds). Make sure to encode the URL parameter in the updateStatus and pollStatus with globally unique IDs to allow your service to distinguish callbacks.

remoteStatusService: { 
    updateStatus: 'http://.../?id=some_guid_here', 
    pollStatus: 'http://.../?id=some_guid_here' 
}

properties

The properties map is used to pass properties to configure the recorder after its launched.  For example if you are using the Basic Uploader then it will have a set of properties needed which you will pass via the properties map.

properties: { name: 'value', ... },

There are also a few properties which can be used regardless of the Uploader chosen:

showManager

When using the screen recorder and video editor you can launch the editor without first doing a screencast to open a window showing local recordings on the computer by setting this property to true. 

{ "showManager": true }

SOMLauncher.setMarkInstall()

If you set the checkInstallMark:true (in the options to the launch() function), use this function to mark when you have shown the download to the user. This helps the launcher to only try the protocol launch if the install was downloaded. If the install has not been marked during this instance of browsing, then the launch will call back with result.protocolNoInstallMarked = "true" .