Page tree
Skip to end of metadata
Go to start of metadata

Abstract

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 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.

You can also check getaroom.io, which is slightly more complex (it's a full size application) but demonstrates the end result very well.

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 the following 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 were setting video.srcObject, or using attachMediaStream, or reattachMediaStream, you NEED to change the code as follow:

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

// same idea 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 attacheMediaStream
<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 come and check that list from time to time. You may contact us on our mailing list for specific requests (with a reason why it is relevant!).

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 by raising a ticket with support.

  • No labels