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;"
I am NOT using AdapterJS
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.