This document provides helpful guidelines to help you integrate the Temasys WebRTC Plugin with your WebRTC-based web-app.

Once this is done, you app should run seamlessly on IE and Safari*.

Temasys provides a polyfill named AdapterJS (AJS) which basically makes the plugin a drop-in, requiring almost no changes on your application.
Using AJS is not mandatory but is strongly recommended as it simplifies the integration process significantly.

If you encounter problems while going through this tutorial, please report them to our support portal.


Start with an example

Temasys maintains a few examples to demonstrate our plugin and its integration : GitHub | Live version

The examples are very simple and designed to be understood immediately.



AdapterJS - AJS

Adapter.js is originally a file that hides the differences between Mozilla Firefox and Google Chrome's implementations of WebRTC. 

We provide an extended version of it (AdapterJS) which integrates Microsoft Internet Explorer and Apple Safari* as well.


When using a WebRTC-ready browser, AJS only hides the browser differences. When your browser is not plugin ready, the plugin will automatically be started.


The code is on Github: https://github.com/Temasys/AdapterJS. 

You can also directly import the latest version from our CDN. See the release section.


If you are already using Google's version of the Adapter.js, you can simply replace it with the Temasys AdapterJS. 

Compatibility with the Google version is continuously maintained. 


Adapter.js licensing

The Temasys fork of Adapter.js (AdapterJS) is released under the Apache License, Version 2.0. Details of the complete terms of this license can be found here.

Please also be aware that the original Adapter.js is released with these license terms.


Changes in your HTML code

You just need to add the following line to your HTML page:

<script src="https://cdn.temasys.com.sg/adapterjs/0.15.x/adapter.debug.js"></script>


Changes in your JavaScript code


1 – Starting your application when the WebRTC features are available

Your browser might take some time to start the plugin (a few 100ms).

You application will need to wait for it before using any WebRTC feature.


You have two choices to start your application:


Recommended solution - Callback

Rely on the AdapterJS.webRTCReady function.

The callback provided as argument will be called as soon as the WebRTC API is ready, whether it is natively (Chrome, Firefox), or using the plugin.

If the WebRTC API is already available, your callback will be invoked immediately.

AdapterJS.webRTCReady(function(isUsingPlugin) {
    // The WebRTC API is ready.
    // isUsingPlugin: true if the WebRTC plugin is being used, false otherwise
    getUserMedia(constraints, successCb, failCb);
});



Compatibility solution - "Just do it"

Simply start your application ignoring the WebRTC initialisation time.

The adapter will make your application wait until the plugin is ready. 

Be aware that this waiting will in some cases block your application code and will use the CPU heavily during this waiting period.

getUserMedia(constraints, successCb, failCb); // I am not using the callback, this call will wait for the WebRTC API to be ready



2 – Playing streams

The plugin cannot interact with your <audio>/<video> element.

In order to render the streams you receive, your <audio>/<video> tags will automatically be replaced by <object> tags controlled by the plugin.

In order to keep your references alive, you need to keep them updated.


Every time you set video.srcObject, or use attachMediaStream, or reattachMediaStream, you NEED to change the code as follow:

// attachMediaStream(myVideoElement, myStream) //old version

myVideoElement = attachMediaStream(myVideoElement, myStream) // new version


// similarly for reattachMediaStream

toVideoElement = reattachMediaStream(toVideoElement, fromVideoElement) // new version


If you have additional references of the <audio>/<video> element in your code, you NEED to update them as well.

If you have conditional CSS stylings on <audio>/<video> elements, you NEED to extend them to the plugin <object> elements.


In Chrome and Firefox, attachMediaStream and reattachMediaStream will return your original <audio>/<video> tags. Thus your reference won't be changed.

In browsers using the plugin, they will return a reference to the new plugin <object>.


AttachMediaStream must be called after the video element in injected into the DOM


AttachMediaStream MUST be called AFTER the <audio>/<video> element was injected into the DOM.
You CANNOT call attachMediaStream on a <audio>/<video> element you are creating in your JS code but haven't injected yet.

For the video and sound to be rendered, the element must also be visible. That is, not "display: none;" or in a <div> that is "display: none;"


What does attachMediaStream do?

The adapter copies some values from your original <audio>/<video> element:

  • the element position in the DOM
  • the element id
  • the element size
  • the element event handlers

For example, this DOM element before attachMediaStream

<video id="localVideoElement" muted></video>


will be changed for after attachMediaStream

<object id="localVideoElement" type="application/x-temwebrtcplugin" width="308px" height="225px">
    <param name="pluginId" value="localVideoElement"> <param name="pageId" value="azvab8em8ceopqfr"> 
    <param name="windowless" value="true"> 
    <param name="streamId" value="LocalStream"> 
</object>
<!-- 
    The id and element size are copied from the original element
    The element is not muted anymore
    The <object> elements you use to render the streams should have a param windowless set to true
    The <object> elements you use to access the plugin should have a param windowless set to false
-->



I am NOT using AdapterJS

It gets more complicated.


Temasys strongly encourages you to use our extension of AdapterJS.


Temasys makes sure that the plugin and AdapterJS are always compatible. If you don't use AdapterJS, you might have to update you code manually for each new release of the plugin. You are, however, free to use our plugin without AdapterJS. You should then be aware that this will generate a non-negligible amount of work.


If you choose not to use AdapterJS, you will need to reproduce AdapterJS logic in your own code (browser detection, plugin injection in the DOM, video elements replacement, etc)


Attributes of the Plugin object element

As we have to use our plugin object element instead of the <audio> or <video> tag, only some of the HTML element attributes are available. Here is the list of the attributes you can use today:

  • children
  • width
  • height
  • style
  • selected
  • nodeName
  • parentNode


More attributes might be enabled in the future, so do check this list from time to time. You can contact us via our support portal or your Account Manager for specific requests.

Note also that since the plugin also has to use custom JavaScript objects internally, some functionality will not work as you might expect. For example: JSON.stringify a plugin JS Object


JSON.stringify(myMediaStream); // will throw an error as JSON.stringify was never implemented to support object elements.


Congratulations!

Your website should now run perfectly on Safari* and Microsoft Internet Explorer. 

However, if you still have issues, please reach out to us via our support portal.



*With the release of the latest version of Safari, Safari 12, Apple has decided to remove support for third party NPAPI plugins in Safari. This means that third party plugins, including the Temasys WebRTC Plugin for Safari, will no longer work with the new version(s) of Apple Safari. Safari versions prior to Safari 12 can continue to use the Temasys WebRTC Plugin as detailed here.*