cordova-plugin-iosrtc-capacitor
Cordova iOS plugin exposing the ̶f̶u̶l̶l̶ 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 in iOS, right?), which means no need to learn "yet another WebRTC API" and no need to use a specific service/product/provider.
Who?
This plugin was initially developed at eFace2Face, and later maintained by the community, specially by Saúl Ibarra Corretgé (The OpenSource Warrior Who Does Not Burn).
Requirements
In order to make this Cordova plugin run into a iOS application some requirements must be satisfied in both development computer and target devices:
- Xcode >= 11.1 (11A1027)
- iOS >= 10.2 (run on lower versions at your own risk, don't report issues)
swift-version
=> 4.2cordova
>= 7.1.0cordova-ios
>= 4.5.1
Third-Party Supported Library
- WebRTC W3C v1.0.0
- WebRTC.framework => M69
- Janus => 0.7.4
- JSSip => 3.1.2
- Sip.js => 0.15.6
- OpenEasyrtc => 2.0.3
- openvidu => 2.11.0
- Ionic => v8
- Jitsi ~ 3229
Installation
Within your Cordova project:
$ cordova plugin add cordova-plugin-iosrtc-capacitor
(or add it into a <plugin>
entry in the config.xml
of your app).
Building
- Last Tested WebRTC.framework version: M69 on cordova-plugin-iosrtc-capacitor version 6.0.0
- Building: Guidelines for building a Cordova iOS application including the cordova-plugin-iosrtc-capacitor plugin.
- Building
libwebrtc
: Guidelines for building Google's libwebrtc with modifications needed by the cordova-plugin-iosrtc-capacitor plugin (just in case you want to use a different version of libwebrtc or apply your own changes to it).
Sample Application
The cordova-plugin-iosrtc-capacitor-sample
include mutiple example for using cordova-plugin-iosrtc-capacitor
with JsSip, Janus, EasyRTC, and basic WebSocket Signaling. It's is used to test cordova-plugin-iosrtc-capacitor
new release and reproduce reported issues.
Usage
The plugin exposes the cordova.plugins.iosrtc
JavaScript namespace which contains all the WebRTC classes and functions.
var appContainer = document.body;
appContainer.innerHTML = "";
var localStream, localVideoEl;
function TestGetUserMedia() {
localVideoEl = document.createElement('video');
localVideoEl.style.height = "50vh";
localVideoEl.setAttribute('autoplay', 'autoplay');
localVideoEl.setAttribute('playsinline', 'playsinline');
appContainer.appendChild(localVideoEl);
return navigator.mediaDevices.getUserMedia({
video: true,
audio: true
}).then(function (stream) {
console.log('getUserMedia.stream', stream);
console.log('getUserMedia.stream.getTracks', stream.getTracks());
localStream = stream;
localVideoEl.srcObject = localStream;
return localStream;
}).catch(function (err) {
console.log('getUserMedia.error', err, err.stack);
});
}
var pc1, pc2;
var peerConnectionConfig = {
offerToReceiveVideo: true,
offerToReceiveAudio: true,
sdpSemantics: 'unified-plan',
bundlePolicy: 'max-compat',
rtcpMuxPolicy: 'negotiate',
iceServers: [
{
url: "stun:stun.stunprotocol.org"
}
]
};
var peerVideoEl, peerStream;
function TestRTCPeerConnection(localStream) {
pc1 = new RTCPeerConnection(peerConnectionConfig);
pc2 = new RTCPeerConnection(peerConnectionConfig);
var localPeerStream = new MediaStream();
localStream.getTracks().forEach(function (track) {
console.log('pc1.addTrack', track, localPeerStream);
pc1.addTrack(track, localPeerStream);
});
function onAddIceCandidate(pc, can) {
console.log('addIceCandidate', pc, can);
return can && pc.addIceCandidate(can).catch(function (err) {
console.log('addIceCandidateError', err);
});
}
pc1.addEventListener('icecandidate', function (e) {
onAddIceCandidate(pc2, e.candidate);
});
pc2.addEventListener('icecandidate', function (e) {
onAddIceCandidate(pc1, e.candidate);
});
function setPeerVideoStream(stream) {
peerVideoEl = document.createElement('video');
peerVideoEl.style.height = "50vh";
peerVideoEl.setAttribute('autoplay', 'autoplay');
peerVideoEl.setAttribute('playsinline', 'playsinline');
appContainer.appendChild(peerVideoEl);
peerStream = stream;
peerVideoEl.srcObject = peerStream;
}
var useTrackEvent = Object.getOwnPropertyDescriptors(RTCPeerConnection.prototype).ontrack;
if (useTrackEvent) {
setPeerVideoStream(new MediaStream());
pc2.addEventListener('track', function (e) {
console.log('pc2.track', e);
peerStream.addTrack(e.track);
});
} else {
pc2.addEventListener('addstream', function (e) {
console.log('pc2.addStream', e);
setPeerVideoStream(e.stream);
});
}
pc1.addEventListener('iceconnectionstatechange', function (e) {
console.log('pc1.iceConnectionState', e, pc1.iceConnectionState);
if (pc1.iceConnectionState === 'completed') {
console.log('pc1.getSenders', pc1.getSenders());
console.log('pc2.getReceivers', pc2.getReceivers());
}
});
pc1.addEventListener('icegatheringstatechange', function (e) {
console.log('pc1.iceGatheringStateChange', e);
});
pc1.addEventListener('negotiationneeded', function (e) {
console.log('pc1.negotiatioNeeded', e);
return pc1.createOffer().then(function (d) {
var desc = {
type: d.type,
sdp: d.sdp
};
console.log('pc1.setLocalDescription', desc);
return pc1.setLocalDescription(desc);
}).then(function () {
var desc = {
type: pc1.localDescription.type,
sdp: pc1.localDescription.sdp
};
console.log('pc2.setLocalDescription', desc);
return pc2.setRemoteDescription(desc);
}).then(function () {
console.log('pc2.createAnswer');
return pc2.createAnswer();
}).then(function (d) {
var desc = {
type: d.type,
sdp: d.sdp
};
console.log('pc2.setLocalDescription', desc);
return pc2.setLocalDescription(d);
}).then(function () {
var desc = {
type: pc2.localDescription.type,
sdp: pc2.localDescription.sdp
};
console.log('pc1.setRemoteDescription', desc);
return pc1.setRemoteDescription(desc);
}).catch(function (err) {
console.log('pc1.createOffer.error', err);
});
});
}
function TestRTCPeerConnectionLocal() {
var cordova = window.cordova;
if (cordova && cordova.plugins && cordova.plugins.iosrtc) {
cordova.plugins.iosrtc.registerGlobals();
cordova.plugins.iosrtc.debug.enable('*', true);
}
TestGetUserMedia().then(function (localStream) {
TestRTCPeerConnection(localStream);
});
}
if (document.readyState === "complete" || document.readyState === "loaded") {
TestRTCPeerConnectionLocal();
} else {
window.addEventListener("DOMContentLoaded", TestRTCPeerConnectionLocal);
}
In case you'd like to expose the API in the global namespace like regular browsers you can do the following:
document.addEventListener('deviceready', function () {
if (window.device.platform === 'iOS') {
cordova.plugins.iosrtc.registerGlobals();
var adapterVersion = 'latest';
var script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://webrtc.github.io/adapter/adapter-" + adapterVersion + ".js";
script.async = false;
document.getElementsByTagName("head")[0].appendChild(script);
}
});
And that's all. Now you have window.RTCPeerConnection
, navigator.getUserMedia
, etc.
FAQ
See the FAQ.
Documentation
Read the full documentation in the docs folder.
Who Uses It
People and companies using cordova-plugin-iosrtc-capacitor.
If you are using the plugin we would love to hear back from you!
Known Issues
iOS Safari and crash on WebSocket events
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 yet, include the provided ios-websocket-hack.js in your app and load into your index.html
as follows:
<script src="cordova.js"></script>
<script src="ios-websocket-hack.min.js"></script>
HTML5 video API
There is no real media source attached to the <video>
element so some HTML5 video events and properties are artificially emitted/set by the plugin on behalf of the video element.
Methods such as play()
, pause()
are not implemented. In order to pause a video just set enabled = false
on the associated MediaStreamTrack
.
iOS >= 13.3.1 Device support
To run on Devices with iOS >= 13.3.1, you need a valid Apple Developer account to sign the WebRTC dynamic frameworks for more info see https://stackoverflow.com/a/60090629/8691951
Changelog
See CHANGELOG.md.
Author
Iñaki Baz Castillo
Maintainers
Looking for new maintainers. Interested? Comment here.
License
MIT :)