Cordova iOS plugin exposing the full WebRTC W3C JavaScript APIs.
Yet another WebRTC SDK for iOS?
Absolutely not. This plugin exposes the WebRTC W3C API for Cordova iOS apps (you know there is no WebRTC on iOS, right?), which means no need to learn "yet another WebRTC API" and no need to use a specific service/product/provider.
Why?
Check the release announcement at the eFace2Face site.
Resources:
- Plugin entry at the Apache Cordova Plugins Registry.
- Public Google Group for questions and discussions about cordova-plugin-iosrtc.
- Bug Tracker for reporting issues and requesting new features (please don't use the bug tracker for questions or problems, use the Google Group instead).
IMPORTANT: Ensure you check the proper documentation according to the exact version of the cordova-plugin-iosrtc plugin you have installed. On GitHub go to the top of this page and select the appropriate tag within the "branch"/"tag" selector and make it match the plugin version.
Within your Cordova project:
$ cordova plugin add com.eface2face.iosrtcIf you just use the cordova-cli to manage and build your Cordova project then you are done with the usual commans (cordova build ios, etc). Anyhow check the Bridging Header documentation if you use more Swift plugins in your app.
If you build your Cordova application using Xcode then some steps must be done as explained in the documentation.
The plugin exposes the cordova.plugins.iosrtc JavaScript namespace which contains all the WebRTC classes and functions.
var pc = new cordova.plugins.iosrtc.RTCPeerConnection({
iceServers: []
});
cordova.plugins.iosrtc.getUserMedia(
// constraints
{ audio: true, video: true },
// success callback
function (stream) {
console.log('got local MediaStream: ', stream);
pc.addStream(stream);
},
// failure callback
function (error) {
console.error('getUserMedia failed: ', error);
}
);Q: But... wait! Does it mean that there is no window.RTCPeerConnection nor navigator.getUserMedia?
R: A Cordova plugin is supposed to expose its JavaScript stuff in a specific namespace and, personally, I just hate those libraries that pollute the global namespace. Said that, the plugin provides a registerGlobals() method, so you just need the following extra-code in your existing WebRTC app (assuming that Cordova Device Plugin is installed):
// Just for Cordova apps.
document.addEventListener('deviceready', function () {
// Just for iOS devices.
if (window.device.platform === 'iOS') {
cordova.plugins.iosrtc.registerGlobals();
}
});And that's all. Now you have window.RTCPeerConnection, navigator.getUserMedia, etc.
Q: What about <video> elements and video.src = URL.createObjectURL(stream)? do I need custom HTML tags or functions to display WebRTC videos?
R: No. Just use an HTML video element as usual, really. The plugin will properly place a native UIView layer on top of it by respecting its properties such as the CSS display, opacity, visibility, z-index and also horizontal mirror effect with -webkit-transform: scaleX(-1); or equivalent.
Q: Can I place HTML elements (buttons and so on) on top of active <video> elements?
R: Unfortunately not. The native UIView rendering the video stream is placed on top of the HTML view. :(
Q: What about HTML5 video events? Can I rely on video.oncanplay?
R: I see what you mean. As there is no real video attached to the <video> element, media events are artificially emitted by the plugin. The following events are emitted when the MediaStream attached to a video element is ready to render video: onloadedmetadata, onloadeddata, oncanplay, oncanplaythrough. So yes, you can rely on them.
Q: Do I need to call special methods to release/free native WebRTC objects? How are they garbage collected?
R: Good question. An RTCPeerConnection is released when close() is called on it, a MediaStream is released when all its tracks end, and other elements are garbage collected when no longer needed. Basically the same behavior as in a WebRTC capable browser.
Q: What about Android? Why just iOS?
R: In modern versions of Android the WebView component is based on the Chromium open source project which already includes WebRTC (more info). For older versions of Android the CrossWalk project provides new WebView versions with WebRTC support as well.
Read the full documentation in the docs folder.
Check our iOSRTCApp (Google's AppRTC adapted to Cordova iOS with pure HTML5/JavaScript and cordova-plugin-iosrtc).
People and companies using cordova-plugin-iosrtc.
If you are using the plugin we would love to heard back from you!
Don't call plugin methods within WebSocket events (onopen, onmessage, etc). There is an issue in iOS Safari (see issue #12). Instead run a setTimeout() within the WebSocket event if you need to call plugin methods on it.
Or better, just load the provided ios-websocket-hack.js script into your Cordova iOS app and you are done.
As explained above, there is no real media source attached to the <video> element so HTML5 video events are artificially emitted by the plugin on behalf of the video element.
However some properties such as readyState and methods such as play(), pause(), etc do not work as expected (again, there is no real audio/video attached to the <video> element). In order to pause a video just set enabled = false on the associated MediaStreamTrack.
(since version 1.2.8)
iosrtc.registerGlobals()also generateswindow.webkitRTCPeerConnectionandnavigator.webkitGetUserMedia()for backwards compatibility with WebRTC JavaScript wrappers/adapters that assume browser vendor prefixes (webkit,moz) in the underlying WebRTC API.
Iñaki Baz Castillo at eFace2Face, inc.
MIT :)