932 lines
26 KiB
Markdown
932 lines
26 KiB
Markdown
|
|
# WebRTC V2 Simple Calling API + Mobile
|
|||
|
|
|
|||
|
|
[](https://snyk.io/test/npm/webrtc-sdk)
|
|||
|
|
[]()
|
|||
|
|
[]()
|
|||
|
|
|
|||
|
|
> WebRTC SDK Upgraded! ES6, new camera control and 100x less code than v1.
|
|||
|
|
|
|||
|
|
The following demo uses PubNub for signaling to transfer the metadata and establish the peer-to-peer connection. Once the connection is established, the video and voice runs on public Google STUN/TURN servers.
|
|||
|
|
Keep in mind, PubNub can provide the signaling for WebRTC, and requires you to combine it with a hosted WebRTC solution. For more detail on what PubNub does, and what PubNub doesn’t do with WebRTC, check out this article: https://support.pubnub.com/support/solutions/articles/14000043715-does-pubnub-provide-webrtc-and-video-chat-
|
|||
|
|
|
|||
|
|
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](https://www.pubnub.com/).
|
|||
|
|
|
|||
|
|
### Supported WebRTC Features
|
|||
|
|
|
|||
|
|
WebRTC SDK offers many rich features and capabilities to enhance the
|
|||
|
|
WebRTC experience. Here is a list of the options available.
|
|||
|
|
|
|||
|
|
1. Photo Snap Camera Transmit *(STUN-less Firewall Ready)*
|
|||
|
|
1. WebRTC Dialing *(STUN-less Firewall Ready)*
|
|||
|
|
1. WebRTC Call Receiving *(STUN-less Firewall Ready)*
|
|||
|
|
1. JSON App Messaging (chat/signals/etc.) *(STUN-less Firewall Ready)*
|
|||
|
|
1. Multi-party Calling
|
|||
|
|
1. Audio only Calls Optional
|
|||
|
|
1. Broadcasting Mode
|
|||
|
|
1. Instant Connect Dialing Optional
|
|||
|
|
1. Security SSL, AES256, ACL Access Control Management
|
|||
|
|
1. Password Protection via Cipher
|
|||
|
|
1. Event History and Call Records
|
|||
|
|
1. Photo History and Recording Static Snapshots of Calls (only stills)
|
|||
|
|
1. Connectivity Detection and Auto-Recovery
|
|||
|
|
1. Pre-configured Video Element for Streaming Video/Audio
|
|||
|
|
1. Pre-configured Local Camera Video Element for Streaming Video/Audio
|
|||
|
|
1. Network Connectivity Hooks (online/offline)
|
|||
|
|
1. SDK Level Debug Output
|
|||
|
|
|
|||
|
|
### Testing Locally
|
|||
|
|
|
|||
|
|
You need an HTTPS (TLS) File Server. To start a local secure file server:
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
python <(curl -L https://goo.gl/LiW3lp)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Then open your browser and point it to your file in
|
|||
|
|
the directory you ran the python HTTPS server.
|
|||
|
|
|
|||
|
|
```shell
|
|||
|
|
open https://0.0.0.0:4443/your-file-here.html
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
> This is a Simple Python HTTPS Secure Server
|
|||
|
|
> https://gist.github.com/stephenlb/2e19d98039469b9d0134
|
|||
|
|
|
|||
|
|
We posted an answer on
|
|||
|
|
[StackOverflow WebRTC HTTPS](http://stackoverflow.com/a/41969170/524733).
|
|||
|
|
This will get you started testing on your laptop.
|
|||
|
|
|
|||
|
|
### Supported WebRTC Calling API Mobile Devices and Browser
|
|||
|
|
|
|||
|
|
List of supported WebRTC Calling Clients including Android and Chrome.
|
|||
|
|
|
|||
|
|
1. Chrome
|
|||
|
|
2. Firefox
|
|||
|
|
3. Opera
|
|||
|
|
4. Mobile Chrome - Android
|
|||
|
|
5. Mobile Firefox - Android
|
|||
|
|
6. *iOS Native Objective-C Compatible*
|
|||
|
|
6. *Android Native Java Compatible*
|
|||
|
|
|
|||
|
|
### The Basic Concepts of WebRTC Calling
|
|||
|
|
|
|||
|
|
##### Making a WebRTC phone Call
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// Dial Number
|
|||
|
|
var session = phone.dial('123-456');
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
##### Receiving a WebRTC phone Call
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.receive(function(session){
|
|||
|
|
// On Call Receiving
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
##### Adding Video Live Stream
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.receive(function(session){
|
|||
|
|
session.connected(function(session){
|
|||
|
|
// Append Live Video Feed
|
|||
|
|
$('#display-div').append(session.video);
|
|||
|
|
});
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Simple WebRTC Walkthrough
|
|||
|
|
|
|||
|
|
Next we will start with a copy/paste example of our SDK.
|
|||
|
|
This Simple Example Comes in **Two WebRTC Calling Sections**.
|
|||
|
|
|
|||
|
|
1. *Part One* will talk about how you can **Make a WebRTC Call**.
|
|||
|
|
2. *Part Two* will teach you about **Receiving a WebRTC Call**.
|
|||
|
|
|
|||
|
|
#### Making a WebRTC Calling & Receiving - *Part One and Two*
|
|||
|
|
|
|||
|
|
Make your first html file named `dial.html` and copy/paste the following:
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<!-- dial.html -->
|
|||
|
|
|
|||
|
|
<!-- Video Output Zone -->
|
|||
|
|
<div id="video-out"> Making a Call </div>
|
|||
|
|
|
|||
|
|
<!-- Libs and Scripts -->
|
|||
|
|
<script src="https://stephenlb.github.io/webrtc-sdk/js/webrtc-v2.js"></script>
|
|||
|
|
<script>(()=>{
|
|||
|
|
// ~Warning~ You must get your own API Keys for non-demo purposes.
|
|||
|
|
// ~Warning~ Get your PubNub API Keys: https://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){
|
|||
|
|
phone.$('video-out').appendChild(session.video);
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
})();</script>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Live WebRTC Call Dialer
|
|||
|
|
|
|||
|
|
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](https://stephenlb.github.io/webrtc-sdk/)
|
|||
|
|
|
|||
|
|
[](https://stephenlb.github.io/webrtc-sdk/)
|
|||
|
|
|
|||
|
|
You can click the link above to try our live WebRTC Demo
|
|||
|
|
which is powered by our easy to use SDK.
|
|||
|
|
|
|||
|
|
### What Can you build with a WebRTC Simple Calling API?
|
|||
|
|
|
|||
|
|
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**:
|
|||
|
|
|
|||
|
|
1. Amazon Mayday Help Button
|
|||
|
|
2. Salesforce SOS Help Button
|
|||
|
|
3. WebRTC Skype Replica
|
|||
|
|
4. Traditional Phone Replacement
|
|||
|
|
5. Chatroulette
|
|||
|
|
6. VoIP Replacement
|
|||
|
|
7. Customer Support Calls
|
|||
|
|
8. In-bound Sales Calls
|
|||
|
|
9. Easy Remote Meetings
|
|||
|
|
10. Call Assistant or Specialists
|
|||
|
|
11. Big Screen Public Announcemnt
|
|||
|
|
12. Live Presentations
|
|||
|
|
|
|||
|
|
So many different options and even more use cases
|
|||
|
|
that have yet to be discovered.
|
|||
|
|
|
|||
|
|
|
|||
|
|
### What is a WebRTC Session?
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
## API Documentation for WebRTC Calling SDK
|
|||
|
|
|
|||
|
|
The WebRTC Simple SDK API Reference will provide to you all the options
|
|||
|
|
available to you as the developer.
|
|||
|
|
|
|||
|
|
### WebRTC Phone Initialization
|
|||
|
|
##### `PHONE({ ... })`
|
|||
|
|
|
|||
|
|
> Initialize the phone object which can send/receive multiple
|
|||
|
|
WebRTC call sessions without limit.
|
|||
|
|
Be careful as your bandwidth is the true limiter.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
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
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Number
|
|||
|
|
|
|||
|
|
> Your phone number is your true ring-in point of truth.
|
|||
|
|
You can set your phone number at init time from the
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var phone = PHONE({ number : '1234567890' });
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Local Camera Video Element
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
$('#display-div').append(phone.video);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone SSL Mode
|
|||
|
|
|
|||
|
|
> You can enable SSL signalling mode for the local client device
|
|||
|
|
by setting the `ssl : true` parameter at init.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var phone = PHONE({
|
|||
|
|
ssl : true
|
|||
|
|
...
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Cipher AES 256 Crypto Mode
|
|||
|
|
|
|||
|
|
> 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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var phone = PHONE({
|
|||
|
|
cipher_key : 'SUPER-SECRET-PASSWORD-HERE'
|
|||
|
|
...
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Audio Only Mode
|
|||
|
|
|
|||
|
|
> You can disable video codec and stream only Audio by setting
|
|||
|
|
the following param in your init code.
|
|||
|
|
Set `video : false` in the media section.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var phone = PHONE({
|
|||
|
|
media : { audio : true, video : false }
|
|||
|
|
...
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Mobile Calling on Android
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
## WebRTC Photo Sharing *Bonus STUN-less Ready*
|
|||
|
|
|
|||
|
|
You can easily snap a photo from the video stream and
|
|||
|
|
send it to your friends in an instant.
|
|||
|
|
You can think of this as an **Instagram WebRTC** style.
|
|||
|
|
Also Photo Sharing works through Corprate Enterprise Firewalls.
|
|||
|
|
|
|||
|
|
### WebRTC Camera Photo Sharing Broadcast
|
|||
|
|
##### `phone.snap()`
|
|||
|
|
|
|||
|
|
> Broadcast your camera photo to all connected sessions.
|
|||
|
|
Also get the IMG data as base64 supported format
|
|||
|
|
for local display if desired.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.ready(function(){
|
|||
|
|
// Auto Send Camera's Photo to all connected Sessions.
|
|||
|
|
var photo = phone.snap();
|
|||
|
|
$('#photo-div').append(photo.image);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Camera Photo Share
|
|||
|
|
##### `session.snap()`
|
|||
|
|
|
|||
|
|
> Send your camera's latest frame as raw IMG to
|
|||
|
|
a specific call session.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.ready(function(){
|
|||
|
|
var session = phone.dial('4321');
|
|||
|
|
var photo = session.snap();
|
|||
|
|
$('#photo-div').append(photo.image);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Prevent Camera from Starting Automatically
|
|||
|
|
|
|||
|
|
By default the WebRTC SDK starts user's camera. You can optionally prevent this by setting the `autocam` flag to `false`. Here is an example of disabling the camera on initialization.
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<!-- dial.html -->
|
|||
|
|
<div id="number"></div>
|
|||
|
|
|
|||
|
|
<button id="startcam">Start Camera</button>
|
|||
|
|
<button id="startcall">Start Call</button><input id="dial">
|
|||
|
|
|
|||
|
|
<!-- Video Output Zone -->
|
|||
|
|
<div id="video-out"></div>
|
|||
|
|
|
|||
|
|
<!-- Libs and Scripts -->
|
|||
|
|
<script src="https://stephenlb.github.io/webrtc-sdk/js/webrtc-v2.js"></script>
|
|||
|
|
<script>(=>(){
|
|||
|
|
|
|||
|
|
// ~Warning~ You must get your own API Keys for non-demo purposes.
|
|||
|
|
// ~Warning~ Get your PubNub API Keys: https://www.pubnub.com/get-started/
|
|||
|
|
// The phone *number* can by any string value
|
|||
|
|
var number = Math.ceil(Math.random()*10000);
|
|||
|
|
var ready = false;
|
|||
|
|
var session = null;
|
|||
|
|
var phone = PHONE({
|
|||
|
|
number : number
|
|||
|
|
, autocam : false
|
|||
|
|
, publish_key : 'pub-c-561a7378-fa06-4c50-a331-5c0056d0163c'
|
|||
|
|
, subscribe_key : 'sub-c-17b7db8a-3915-11e4-9868-02ee2ddab7fe'
|
|||
|
|
, ssl : true
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// Show Number
|
|||
|
|
phone('number').innerHTML = 'Number: ' + number;
|
|||
|
|
|
|||
|
|
// Start Camera
|
|||
|
|
phone.bind( 'mousedown,touchstart', phone.$('startcam'), function() {
|
|||
|
|
phone.startcamera();
|
|||
|
|
return false;
|
|||
|
|
} );
|
|||
|
|
|
|||
|
|
// Start Call
|
|||
|
|
phone.bind( 'mousedown,touchstart', phone.$('startcall'), function() {
|
|||
|
|
console.log('calling');
|
|||
|
|
session = phone.dial(phone.$('dial').value);
|
|||
|
|
return false;
|
|||
|
|
} );
|
|||
|
|
|
|||
|
|
// 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.
|
|||
|
|
ready = true;
|
|||
|
|
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// When Call Comes In or is to be Connected
|
|||
|
|
phone.receive(function(session){
|
|||
|
|
|
|||
|
|
// Display Your Friend's Live Video
|
|||
|
|
session.connected(function(session){
|
|||
|
|
phone.$('video-out').appendChild(session.video);
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
})();</script>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## WebRTC JSON Messaging *Bonus STUN-less Ready*
|
|||
|
|
|
|||
|
|
Adding extra realtime capabilities between connected parties
|
|||
|
|
is essential for creating collaborative and chat features.
|
|||
|
|
You can do that with PubNub's WebRTC SDK easily without
|
|||
|
|
firewall restrictions from corporate policies.
|
|||
|
|
|
|||
|
|
### Message Broadcasting to All Sessions
|
|||
|
|
##### `phone.send(...)`
|
|||
|
|
|
|||
|
|
> Send a JSON message to all connected sessions.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.send({ text : 'HI!' });
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Receive a JSON message from Any Session
|
|||
|
|
##### `phone.message(function(message){ ... })`
|
|||
|
|
|
|||
|
|
> Get all messages sent from any session.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.message(function( session, message ) {
|
|||
|
|
show_chat( session.number, message.text );
|
|||
|
|
} );
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Send a JSON Message to One Session
|
|||
|
|
##### `session.send(...)`
|
|||
|
|
|
|||
|
|
> You can send a direct JSON message to one session only.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.send({ text : 'Hi there!' });
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Receive a JSON message from One Session
|
|||
|
|
##### `session.message(function(){ ... })`
|
|||
|
|
|
|||
|
|
> You can set callbacks to capture JSON messages
|
|||
|
|
from a specific call session.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.message(function( session, message ) {
|
|||
|
|
show_chat( session.number, message.text );
|
|||
|
|
} );
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Ready
|
|||
|
|
##### `phone.ready(function(){ ... })`
|
|||
|
|
|
|||
|
|
> 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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.ready(function(){
|
|||
|
|
// Ready to make Calls
|
|||
|
|
var session = phone.dial("my-friend's-number");
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Receiving Calls
|
|||
|
|
##### `phone.receive(function(session){ ... })`
|
|||
|
|
|
|||
|
|
> 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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.receive(function(session){
|
|||
|
|
session.connected(function(session){ /* call connected */ });
|
|||
|
|
session.ended(function(session){ /* call ended */ });
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Get Your Phone Number
|
|||
|
|
##### `var num = phone.number()`
|
|||
|
|
|
|||
|
|
> 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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var num = phone.number();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Get Caller Phone Number
|
|||
|
|
##### `var num = session.number`
|
|||
|
|
|
|||
|
|
> To access current caller number, check the session
|
|||
|
|
object number property `session.number`.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var num = session.number;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Get Call Start Time
|
|||
|
|
##### `var start = session.started`
|
|||
|
|
|
|||
|
|
> The Session object stores the call start time which
|
|||
|
|
you can use to display call timer on the screen.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var start = session.started;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Call History via PubNub
|
|||
|
|
##### `phone.history(...)`
|
|||
|
|
|
|||
|
|
> You can get the call history of a phone number by issuing
|
|||
|
|
a PubNub History call on the phne number.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.history({
|
|||
|
|
number : '1234',
|
|||
|
|
history : function(call_history) {
|
|||
|
|
console.log(call_history);
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Dialing Numbers
|
|||
|
|
##### `phone.dial(number)`
|
|||
|
|
|
|||
|
|
> You can easily make WebRTC calls by executing the `dial()` method.
|
|||
|
|
The number can be any string value such as `"415-555-5555"`.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var session = phone.dial(number);
|
|||
|
|
|
|||
|
|
session.connected(function(session){ /* call connected */ });
|
|||
|
|
session.ended(function(session){ /* call ended */ });
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Multi-party Dialing
|
|||
|
|
##### `phone.dial(number)`
|
|||
|
|
|
|||
|
|
> The PubNub WebRTC Phone Dialer and Receiver supports
|
|||
|
|
unlimited party in/out calling.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
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 */ });
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Video and Audio Broadcasting Mode
|
|||
|
|
##### `phone.receive(function(session){ ... })`
|
|||
|
|
|
|||
|
|
> You can receive unlimited inbound calls and become a broadcast
|
|||
|
|
beacon stream.
|
|||
|
|
You are limited by your bandwidth upload capacity.
|
|||
|
|
|
|||
|
|
## Broadcaster with Audience Members
|
|||
|
|
|
|||
|
|
You'll start by opening the stream for the broadcaster so audience members can join in.
|
|||
|
|
Start broadcasting as the broadcaster:
|
|||
|
|
|
|||
|
|
### Broadcaster
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
// Initialize the Broadcaster's Device
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
var broadcaster = PHONE({
|
|||
|
|
number : "BROADCASTER", // If you want more than one broadcaster, use unique ids
|
|||
|
|
publish_key : 'pub-c-561a7378-fa06-4c50-a331-5c0056d0163c',
|
|||
|
|
subscribe_key : 'sub-c-17b7db8a-3915-11e4-9868-02ee2ddab7fe',
|
|||
|
|
ssl : true
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
// Wait for New Viewers to Join
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
broadcaster.receive(function(new_viewer){
|
|||
|
|
new_viewer.connected(function(viewer){ /* ... */ }); // new viewer joined
|
|||
|
|
new_viewer.ended(function(viewer){ /* ... */ }); // viewer left
|
|||
|
|
//new_viewer.hangup(); // if you want to block the viewer
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Viewer
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
// Initialize the Viewer's Device
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
var viewer = PHONE({
|
|||
|
|
number : "VIEWER-"+new Date,
|
|||
|
|
publish_key : 'pub-c-561a7378-fa06-4c50-a331-5c0056d0163c',
|
|||
|
|
subscribe_key : 'sub-c-17b7db8a-3915-11e4-9868-02ee2ddab7fe',
|
|||
|
|
ssl : true
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
// Join a Broadcast as a Viewer
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
viewer.ready(function(){
|
|||
|
|
var broadcaster = phone.dial("BROADCASTER");
|
|||
|
|
});
|
|||
|
|
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
// Show Broadcast's Video Stream
|
|||
|
|
// =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
|
|||
|
|
viewer.receive(function(broadcaster){
|
|||
|
|
broadcaster.connected(function(broadcaster){
|
|||
|
|
document.body.appendChild(broadcaster.video);
|
|||
|
|
});
|
|||
|
|
broadcaster.ended(function(broadcaster){ /* broadcast ended */ });
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Hangup
|
|||
|
|
##### `phone.hangup()`
|
|||
|
|
|
|||
|
|
> 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 method `session.hangup()`
|
|||
|
|
which will only hangup that call session.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// hangup all calls
|
|||
|
|
phone.hangup();
|
|||
|
|
|
|||
|
|
// hangup single session
|
|||
|
|
session.hangup();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Network Events
|
|||
|
|
##### `PHONE.disconnect(function(){ ... })`
|
|||
|
|
|
|||
|
|
> You need to keep track of the connectivity state of your local
|
|||
|
|
network connection. You can do that using these helper methods.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
PHONE.connect(function(){ console.log('network LIVE.') })
|
|||
|
|
PHONE.disconnect(function(){ console.log('network GONE.') })
|
|||
|
|
PHONE.reconnect(function(){ console.log('network BACK!') })
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Unable to Initialize
|
|||
|
|
##### `phone.unable(function(details){ ... })`
|
|||
|
|
|
|||
|
|
> Some devices or in certain situations the phone may not initialize.
|
|||
|
|
We give you a simple callback for when the phone startup fails.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.unable(function(details){
|
|||
|
|
console.log("Phone is unable to initialize.");
|
|||
|
|
console.log("Try reloading, or give up.");
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Stop Camera and Mic
|
|||
|
|
##### `phone.camera.stop()`
|
|||
|
|
|
|||
|
|
> You may want to Stop the Camera/Mic recording.
|
|||
|
|
By default the camera and mic are turned on as soon as possible.
|
|||
|
|
This allows for faster calling connection speeds.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var streamref = phone.camera.stop();
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Debugging
|
|||
|
|
##### `phone.debug(function(details){ ... })`
|
|||
|
|
|
|||
|
|
> You might want to see under the covers of WebRTC Calling by
|
|||
|
|
enabling debugging mode on the WebRTC SDK.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.debug(function(details){
|
|||
|
|
console.log(details);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Phone Auto Hangup and Goodbye on Unload
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
### The WebRTC Session Object
|
|||
|
|
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.ended(function(session){})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
A session object is generated automatically for you upon dialing
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var session = phone.dial('...')
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
and also inside registered event callbacks.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
phone.receive(function(session){})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Number
|
|||
|
|
##### `session.number`
|
|||
|
|
|
|||
|
|
> Returns the 2nd party's (caller/callee)
|
|||
|
|
Phone Number associated with the Call Session.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var session = phone.dial('12345');
|
|||
|
|
console.log(session.number == '12345');
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Connected Callback
|
|||
|
|
##### `session.connected(function(session){})`
|
|||
|
|
|
|||
|
|
> Sets the callback for when the session is connected and
|
|||
|
|
the **video** stream is ready to display.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.connected(function(session){
|
|||
|
|
var body = phone.$$('body')[0];
|
|||
|
|
body.appendChild(session.video);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Ended Callback
|
|||
|
|
##### `session.ended(function(session){})`
|
|||
|
|
|
|||
|
|
> The session has ended by one of the parties.
|
|||
|
|
Any secondary session will continue to stream.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.ended(function(session){
|
|||
|
|
sounds.play('sound/goodbye');
|
|||
|
|
console.log("Bye!");
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Hangup
|
|||
|
|
##### `session.hangup()`
|
|||
|
|
|
|||
|
|
> End the session right now.
|
|||
|
|
The `ended` callback will fire for both connected parties.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
$("#hangup").click(function(){
|
|||
|
|
// End the call
|
|||
|
|
session.hangup();
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Video Element
|
|||
|
|
##### `session.video`
|
|||
|
|
|
|||
|
|
> The Session Video Element is Accessable and Ready
|
|||
|
|
inside the `connected` only.
|
|||
|
|
The Session Video ref is an HTML Video Element `<video>`.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.connected(function(session){
|
|||
|
|
var body = phone.$$('body')[0];
|
|||
|
|
var video = session.video;
|
|||
|
|
|
|||
|
|
body.appendChild(video);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session Image Element
|
|||
|
|
##### `session.image`
|
|||
|
|
|
|||
|
|
> The Session Image Element is Accessable and Ready
|
|||
|
|
inside the `thumbnail`, `connected` and `ended` callbacks.
|
|||
|
|
The Session Image ref is an HTML Image Element `<img>`.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
session.thumbnail(function(session){
|
|||
|
|
var body = phone.$$('body')[0];
|
|||
|
|
var image = session.image;
|
|||
|
|
|
|||
|
|
body.appendChild(image);
|
|||
|
|
});
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Session RTCPeerConnection Reference
|
|||
|
|
##### `session.pc`
|
|||
|
|
|
|||
|
|
> Reference to WebRTC RTCPeerConnection.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
var sesionPeerConnection = session.pc;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Adding Custom STUN and TURN Servers
|
|||
|
|
|
|||
|
|
> You may desire to add your own custom stun or turn servers by using
|
|||
|
|
the `servers` parameter on initialization.
|
|||
|
|
For example http://xirsys.com/ offers paid-stun solution.
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
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"}
|
|||
|
|
]
|
|||
|
|
// ...
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## SDK Possible Upgrade Future Patches
|
|||
|
|
|
|||
|
|
- 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
|
|||
|
|
|
|||
|
|
## Implementation Reference Upgrades
|
|||
|
|
|
|||
|
|
- Pre-Allow Transmit - Before "allow" fire a PubNub message
|
|||
|
|
- Chat on Screen
|
|||
|
|
- Multi-Party Video in GUI
|
|||
|
|
- Full Screen Mode
|
|||
|
|
- Controlling an iFrame
|
|||
|
|
|
|||
|
|
### What is Happens Inside the Simple WebRTC SDK
|
|||
|
|
|
|||
|
|
##### Signaling and Exchanging ICE Candidates via PubNub
|
|||
|
|
|
|||
|
|
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](https://github.com/stephenlb/webrtc-sdk)
|
|||
|
|
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.
|
|||
|
|
|
|||
|
|
#### Signaling Example Code Follows
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<script src="https://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',
|
|||
|
|
ssl : true
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
// 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>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### Generate ICE Candidates Example Code Follows:
|
|||
|
|
|
|||
|
|
```html
|
|||
|
|
<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>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### WebRTC Troubleshooting
|
|||
|
|
|
|||
|
|
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)`.
|
|||
|
|
|