At PubNub we believe simplicity is essential for our SDK usability. We've taken a simplified approach to WebRTC Peer Connections by creating and easy-to-use SDK for developers. The ideas of simplicity should span all platforms and devices too and that's why we also support Android WebRTC mobile calling with compatibility for iOS native Objective-C based WebRTC SDK. This simple developer WebRTC SDK is powered by PubNub Data Stream Network.
WebRTC SDK offers many rich features and capabilities to enhance the WebRTC experience. Here is a list of the options available.
- Photo Snap Camera Transmit (STUN-less Firewall Ready)
- WebRTC Dialing (STUN-less Firewall Ready)
- WebRTC Call Receiving (STUN-less Firewall Ready)
- JSON App Messaging (chat/signals/etc.) (STUN-less Firewall Ready)
- Multi-party Calling
- Audio only Calls Optional
- Broadcasting Mode
- Instant Connect Dialing Optional
- Security SSL, AES256, ACL Access Control Management
- Password Protection via Cipher
- Event History and Call Records
- Photo History and Recording Static Snapshots of Calls (only stills)
- Connectivity Detection and Auto-Recovery
- Pre-configured Video Element for Streaming Video/Audio
- Pre-configured Local Camera Video Element for Streaming Video/Audio
- Network Connectivity Hooks (online/offline)
- SDK Level Debug Output
List of supported WebRTC Calling Clients including Android and Chrome.
- Chrome
- Firefox
- Opera
- Mobile Chrome - Android
- Mobile Firefox - Android
- iOS Native Objective-C Compatible
- Android Native Java Compatible
// Dial Number
var session = phone.dial('123-456');phone.receive(function(session){
// On Call Receiving
});phone.receive(function(session){
session.connected(function(session){
// Append Live Video Feed
$('#display-div').append(session.video);
});
});Next we will start with a copy/paste example of our SDK. This Simple Example Comes in Two WebRTC Calling Sections.
- Part One will talk about how you can Make a WebRTC Call.
- Part Two will teach you about Receiving a WebRTC Call.
Make your first html file named dial.html and copy/paste the following:
<!-- dial.html -->
<!-- Video Output Zone -->
<div id="video-out"> Making a Call </div>
<!-- Libs and Scripts -->
<script src="https://cdn.pubnub.com/pubnub.min.js"></script>
<script src="http://stephenlb.github.io/webrtc-sdk/js/webrtc.js"></script>
<script>(function(){
// ~Warning~ You must get your own API Keys for non-demo purposes.
// ~Warning~ Get your PubNub API Keys: http://www.pubnub.com/get-started/
// The phone *number* can by any string value
var phone = PHONE({
number : '1234',
publish_key : 'pub-c-561a7378-fa06-4c50-a331-5c0056d0163c',
subscribe_key : 'sub-c-17b7db8a-3915-11e4-9868-02ee2ddab7fe',
ssl : true
});
// As soon as the phone is ready we can make calls
phone.ready(function(){
// Dial a Number and get the Call Session
// For simplicity the phone number is the same for both caller/receiver.
// you should use different phone numbers for each user.
var session = phone.dial('1234');
});
// When Call Comes In or is to be Connected
phone.receive(function(session){
// Display Your Friend's Live Video
session.connected(function(session){
PUBNUB.$('video-out').appendChild(session.video);
});
});
})();</script>If you combine both the WebRTC Dialer and the WebRTC Receiver you will get a complete working phone. We have a live running WebRTC Demo which uses our WebRTC SDK. This demo includes a soft-touch UI for an easy calling experience.
try the live WebRTC Dialing: WebRTC Simple Calling API + Mobile
You can click the link above to try our live WebRTC Demo which is powered by our easy to use SDK.
There are a plethera of important and useful applications which may be built using the PubNub WebRTC Calling SDK. I have cataloged a list of ideas for WebRTC Use Cases:
- Amazon Mayday Help Button
- Salesforce SOS Help Button
- WebRTC Skype Replica
- Traditional Phone Replacement
- Chatroulette
- VoIP Replacement
- Customer Support Calls
- In-bound Sales Calls
- Easy Remote Meetings
- Call Assistant or Specialists
- Big Screen Public Announcemnt
- Live Presentations
So many different options and even more use cases that have yet to be discovered.
A WebRTC Session is a reference to a call instance
between two connected parties.
The idea is the session is active as long as the two parties are connected.
Once one party member disconnects or leaves, the session will be terminated.
You have access to several helper methods for
session.connected() and session.ended() events.
The WebRTC Simple SDK API Reference will provide to you all the options available to you as the developer.
Initialize the phone object which can send/receive multiple WebRTC call sessions without limit. Be careful as your bandwidth is the true limiter.
var phone = PHONE({
number : '1234567890',
publish_key : 'pub-c-561a7378-fa06-4c50-a331-5c0056d0163c',
subscribe_key : 'sub-c-17b7db8a-3915-11e4-9868-02ee2ddab7fe',
media : { audio : true, video : true },
ssl : true
})Your phone number is your true ring-in point of truth. You can set your phone number at init time from the
var phone = PHONE({ number : '1234567890' });We provide you easy access to your local camera with a pre-initialized video element that is easy to access. Simply append the element to your DOM and the feed will stream automatically.
$('#display-div').append(phone.video);You can enable SSL signalling mode for the local client device by setting the
ssl : trueparameter at init.
var phone = PHONE({
ssl : true
...
})You can enable AES256 Encryption (essentially password mode) on your phone for additional security. You're friends have to know your password to call you. AES256 option allows you to password protect your phone and only give access to people you know.
You have to give your friend your password before they can call you.
var phone = PHONE({
cipher_key : 'SUPER-SECRET-PASSWORD-HERE'
...
})You can disable video codec and stream only Audio by setting the following param in your init code. Set
video : falsein the media section.
var phone = PHONE({
media : { audio : true, video : false }
...
})WebRTC calling on Android is web-ready compatible and works out-of-the-box today without modifications or additional code. Also WebRTC Calling is supported for Android and iOS Native too.
You can easily snap a photo from the video stream and send it to your friends in an instnat. You can think of this as an Instagram WebRTC style. Also Photo Sharing works through Corprate Enterprise Firewalls.
Broadcast your camera photo to all connected sessions. Also get the IMG data as base64 supported format for local display if desired.
phone.ready(function(){
// Auto Send Camera's Photo to all connected Sessions.
var photo = phone.snap();
$('#photo-div').append(photo.image);
});Send your camera's latest frame as raw IMG to a specific call session.
phone.ready(function(){
var session = phone.dial('4321');
var photo = session.snap();
$('#photo-div').append(photo.image);
});Adding extra realtime capabilities between connected parties is essential for creating collaberative and chat features. You can do that with PubNub's WebRTC SDK easily without firewall restrictions from corporate policies.
Send a JSON message to all connected sessions.
phone.send({ text : 'HI!' });Get all messages sent from any session.
phone.message(function( session, message ) {
show_chat( session.number, message.text );
} );You can send a direct JSON message to one session only.
session.send({ text : 'Hi there!' });You can set callbacks to capture JSON messages from a specific call session.
session.message(function( session, message ) {
show_chat( session.number, message.text );
} );Making calls is easy but you can only do it when the phone is ready to issue the signals properly and the local interfaces have been configured such as audio/video media.
phone.ready(function(){
// Ready to make Calls
var session = phone.dial("my-friend's-number");
});It's really ease to setup your phone to receive calls using the
phone.receive()method. This method expects a callback function and will pass the WebRTC Session object as the only parameter.
phone.receive(function(session){
session.connected(function(session){ /* call connected */ });
session.ended(function(session){ /* call ended */ });
});Sometimes you need to access the phone number that was set during initialization time. You can do that by calling
phone.number()method which returns the setup number.
var num = phone.number();To access current caller number, check the session object number property
session.number.
var num = session.number;The Session object stores the call start time which you can use to display call timer on the screen.
var start = session.started;You can get the call history of a phone number by issuing a PubNub History call on the phne number.
phone.history({
number : '1234',
history : function(call_history) {
console.log(call_history);
}
});You can easily make WebRTC calls by executing the
dial()method. The number can be any string value such as"415-555-5555".
var session = phone.dial(number);
session.connected(function(session){ /* call connected */ });
session.ended(function(session){ /* call ended */ });The PubNub WebRTC Phone Dialer and Receiver supports unlimited party in/out calling.
var sessions = [];
sessions.push(phone.dial('friend-one'));
sessions.push(phone.dial('friend-two'));
sessions.push(phone.dial('friend-three'));
sessions.push(phone.dial('friend-four'));
sessions.push(phone.dial('friend-five'));
sessions.forEach(function(friend){
friend.connected(function(session){ /* call connected */ });
friend.ended(function(session){ /* call ended */ });
});You can receive unlimited inbound calls and become a broadcast beacon stream. You are limited by your bandwidth upload capacity.
There are two ways to hangup WebRTC calls. You can use the phone-level method
phone.hangup()which will hangup all calls at once. Or you can use the session-level methodsession.hangup()which will only hangup that call session.
// hangup all calls
phone.hangup();
// hangup single session
session.hangup();You need to keep track of the connectivity state of your local network connection. You can do that using these helper methods.
PHONE.connect(function(){ console.log('network LIVE.') })
PHONE.disconnect(function(){ console.log('network GONE.') })
PHONE.reconnect(function(){ console.log('network BACK!') })Some devices or in certain situations the phone may not initialize. We give you a simple callback for when the phone startup fails.
phone.unable(function(details){
console.log("Phone is unable to initialize.");
console.log("Try reloading, or give up.");
});You might want to see under the covers of WebRTC Calling by enabling debugging mode on the WebRTC SDK.
phone.debug(function(details){
console.log(details);
});The WebRTC Calling SDK will attempt an automatic goodbye upon graceful
disconnection attempts.
This allows the 2nd party on the other end of the phone line to
receive a call ended signal.
This happens automatically.
A WebRTC Session represents the connection between two parties with access
to the session.video element as well as the place to register
event callbacks as needed such as session.connected
and also the ended callback for when the call disconnects or hangs up.
session.ended(function(session){})A session object is generated automatically for you upon dialing
var session = phone.dial('...')and also inside registered event callbacks.
phone.receive(function(session){})Returns the 2nd party's (caller/callee) Phone Number associated with the Call Session.
var session = phone.dial('12345');
console.log(session.number == '12345');Sets the callback for when the session is connected and the video stream is ready to display.
session.connected(function(session){
var body = document.getElementsByTagName('body')[0];
body.appendChild(session.video);
});The session has ended by one of the parties. Any secondary session will continue to stream.
session.ended(function(session){
sounds.play('sound/goodbye');
console.log("Bye!");
});End the session right now. The
endedcallback will fire for both connected parties.
$("#hangup").click(function(){
// End the call
session.hangup();
});The Session Video Element is Accessable and Ready inside the
connectedonly. The Session Video ref is an HTML Video Element<video>.
session.connected(function(session){
var body = document.getElementsByTagName('body')[0];
var video = session.video;
body.appendChild(video);
});The Session Image Element is Accessable and Ready inside the
thumbnail,connectedandendedcallbacks. The Session Image ref is an HTML Image Element<img>.
session.thumbnail(function(session){
var body = document.getElementsByTagName('body')[0];
var image = session.image;
body.appendChild(image);
});Reference to WebRTC RTCPeerConnection.
var sesionPeerConnection = session.pc;You may desire to add your own custom stun or turn servers by using the
serversparameter on initialization. For example http://xirsys.com/ offers paid-stun solution.
var phone = PHONE({
servers : [
{"username":"free","url":"turn:127.0.0.1?transport=udp","credential":"free"},
{"username":"free","url":"turn:127.0.0.1?transport=tcp","credential":"free"}
]
// ...
})- Race - During Ring/Receive Handshake, a Hangup will create Race
- Wire-pulled Disconnect Detect via DataChannels Pings
- 5 Second Timeout to Retry with 30 Second of Retries
- Auto-reconnect re-SDP/ICE Recovery
- Custom Message Events
- Presence
- Call History
- User Lists
- Pre-Allow Transmit - Before "allow" fire a PubNub message
- Chat on Screen
- Multi-Party Video in GUI
- Full Screen Mode
- Controlling an iFrame
The goal is to exchange ICE candidate packets between two peers.
ICE candidate packets are structured payloads which contain possible
path recommendations between two peers.
You can use a lib which will take care of the nitty gritty such as
WebRTC Simple Calling API + Mobile
however below is the general direction that is taken inside the SDK itself.
Note that the demonstration code below is intintionally incomplete. Note however the PubNub WebRTC Signaling SDK properly covers most Calling Situations.
<script src="http://cdn.pubnub.com/pubnub-3.6.3.min.js"></script>
<script>(function(){
// INIT P2P Packet Exchanger
var pubnub = PUBNUB({
publish_key : 'demo',
subscribe_key : 'demo'
})
// You need to specify the exchange channel for the peers to
// exchange ICE Candidates.
var exchange_channel = "p2p-exchange";
// LISTEN FOR SDP and ICE CANDIDATES
pubnub.subscribe({
channel : exchange_channel,
message : receive_ice_candidates
})
// SDP and ICE CANDIDATES RECEIVER PROCESSOR FUNCTION
function receive_ice_candidates(ice_candidate) {
// Attempt peer connection or upgrade route if better route...
console.log(ice_candidate);
// ... RTC Peer Connection upgrade/attempt ...
}
// SEND SDP and ICE CANDIDATES
function send_ice_candidate(ice) {
pubnub.publish({
channel : exchange_channel,
message : ice
})
}
})();</script><script>(function(){
// CREATE ICE CANDIDATES
var pc = new RTCPeerConnection();
navigator.getUserMedia( {video: true}, function(stream) {
pc.onaddstream({stream:stream});
pc.addStream(stream);
pc.createOffer( function(offer) {
pc.setLocalDescription(
new RTCSessionDescription(offer),
send_ice_candidate,
error
);
}, error );
} );
})();</script>You may need to force clear your cache on your device, close the app completley, then restart it.
This is uncommon.
You can also enable debugging at the code-level by hooking onto the phone.unable(fn) and phone.debug(fn).