Channel Recorder API

8min
Overview
With the Channel Recorder API you can embed a "Record Screencast" button any where to upload to your Channel on ScreenPal.com.  For example if you wanted to collect tech support bugs from users on your website.
﻿Standard Channel Recorder Tutorial﻿
The API options simply extend the standard Channel Recorder functionality so you can place the button on your own site/tool instead of requiring users to visit our hosted page for the launch. 
These also allow for additional functions such as callbacks, outlined below.

Prerequisite
To use the Recorder API you need the Recorder API enabled plan.  
Team Business with 25 or more creators on plan.
Team Education with 100 or more creators on plan.
Please contact [email protected] to purchase/upgrade your plan if you cannot upgrade your plan in your hosting settings.  

Getting Started
Take a look at our tutorial on Setting up an Embedded Recorder which goes over how to get started by:

Creating a Channel on your ScreenPal.com account

Setting up the recorder to embed.

Copy-and-paste javascript for recorder into your html.
Javascript Settings
When you embed the javascript you can add some extra settings, using customData and callback as exampled below:
JS
<script type="text/javascript" id="som_recorder_RECORDERID" src="//screencast-o-matic.com/api/som.js">
</script><script type="text/javascript">
    SOM.Recorder({
        id: "RECORDERID",
        customData:{"key1":"value1", "key2":"value2" ...},
        callback: function(screencast) {...}
        }).embed();
</script>
<script type="text/javascript" id="som_recorder_RECORDERID" src="//screencast-o-matic.com/api/som.js">
</script><script type="text/javascript">
    SOM.Recorder({
        id: "RECORDERID",
        customData:{"key1":"value1", "key2":"value2" ...},
        callback: function(screencast) {...}
        }).embed();
</script>
﻿
customData
Setting a customData object with key/value pairs will save the data so it's passed back in the callback function and in JSON for the WebHook if you have one defined (see more about WebHook Callback below).

callback
Setting a callback function will allow you to receive a javascript callback after the recorder is closed.  If a screencast is uploaded from the recorder then the function will be called back with a javascript object containing details for the upload OR undefined if no screencast was uploaded.  

When using the javascript callback, the end user should not navigate away from the page where the recorder is launched or else the javascript callback won't be called.

The javascript object will contain the following details:
﻿
JS
{
    "id": "SCREENCASTID",
    "title": "Title entered by user",
    "description": "Description entered by the user (or empty string if nothing was given)",
    "customData": { customData you provided if any }
}
{
    "id": "SCREENCASTID",
    "title": "Title entered by user",
    "description": "Description entered by the user (or empty string if nothing was given)",
    "customData": { customData you provided if any }
}
﻿
If you also check the box in your recorder settings to "Include links and embed tag in javascript callback" then you also get links and an embed tag to what was uploaded:
JS
{
    "id": "SCREENCASTID",
    "title": "Title entered by user",
    "description": "Description entered by the user (or empty string if nothing was given)",
    "customData": { customData provided in javascript },
    "watchLink" : "http://link/ to the playback page for the upload",
    "channelLink" : "http://link/ to the channel page for the upload",
    "downloadLink" : "http://link/ to download the mp4 for upload which expires after 1 hour",
    "embedTag" : "<frame>Tag to embed a player for the upload</frame>"
}
{
    "id": "SCREENCASTID",
    "title": "Title entered by user",
    "description": "Description entered by the user (or empty string if nothing was given)",
    "customData": { customData provided in javascript },
    "watchLink" : "http://link/ to the playback page for the upload",
    "channelLink" : "http://link/ to the channel page for the upload",
    "downloadLink" : "http://link/ to download the mp4 for upload which expires after 1 hour",
    "embedTag" : "<frame>Tag to embed a player for the upload</frame>"
}
﻿
WebHook Callback
You can set up a WebHook callback so a POST request is made from our servers back to your system when an upload is made.  You can supply either an HTTP or HTTPS URL which can also be prefixed with a username and password for basic authentication like: username:password@http://....

The POST request will contain JSON with the same data provided in the javascript callback with all the links to the upload that was created like:
JS
{
    "id": "SCREENCASTID",
    "title": "Title entered by user",
    "description": "Description entered by the user (or empty string if nothing was given)",
    "customData": { customData provided in javascript },
    "watchLink" : "http://link/ to the playback page for the upload",
    "channelLink" : "http://link/ to the channel page for the upload",
    "downloadLink" : "http://link/ to download the mp4 for upload which expires after 1 hour",
    "embedTag" : "<frame>Tag to embed a player for the upload</frame>"
}
{
    "id": "SCREENCASTID",
    "title": "Title entered by user",
    "description": "Description entered by the user (or empty string if nothing was given)",
    "customData": { customData provided in javascript },
    "watchLink" : "http://link/ to the playback page for the upload",
    "channelLink" : "http://link/ to the channel page for the upload",
    "downloadLink" : "http://link/ to download the mp4 for upload which expires after 1 hour",
    "embedTag" : "<frame>Tag to embed a player for the upload</frame>"
}
﻿
If the system fails to post to your server then it will retry until it successfully posts.
Updated 08 May 2024
Migrating to a Newer Solution Builder Version
Get the Latest SDK & API