PeerJS docsSkyWay Version

PeerJS simplifies peer-to-peer data, video, and audio calls.

This guide will show you the basic concepts of the PeerJS API. If you learn better from seeing a working app, see the examples at the bottom of the page.

This document is for NTT Communication's cloud service "SkyWay", a customized version of PeerJS.

Setup

1. Include the Javascript client

Add the PeerJS client library to your webpage.

<script src="https://skyway.io/dist/0.3/peer.min.js"></script>

If you prefer, you can host it yourself: peer.js, peer.min.js, or fork us on Github.

2. Create the Peer object

The Peer object is where we create and receive connections.

var peer = new Peer({key: 'APIKEY'});

You can sign up for your own free key. PeerJS uses PeerServer for session metadata and candidate signaling. You can also run your own PeerServer if you don't like the cloud.

We're now ready to start making connections!

Usage

Every Peer object is assigned a random, unique ID when it's created.

peer.on('open', function(id) {
  console.log('My peer ID is: ' + id);
});

When we want to connect to another peer, we'll need to know their peer id. You're in charge of communicating the peer IDs between users of your site. Optionally, you can pass in your own IDs to the Peer constructor.

Read the Peer API reference for complete information on its options, methods, events, and error handling.

Data connections

Start a data connection by calling peer.connect with the peer ID of the destination peer. Anytime another peer attempts to connect to your peer ID, you'll receive a connection event.

var conn = peer.connect('dest-peer-id');

peer.on('connection', function(conn) { ... });

peer.connect and the callback of the connection event will both provide a DataConnection object. This object will allow you to send and receive data:

conn.on('open', function() {
  // Receive messages
  conn.on('data', function(data) {
    console.log('Received', data);
  });

  // Send messages
  conn.send('Hello!');
});

Read the DataConnection API reference for complete details on its methods and events.

Video/audio calls

Call another peer by calling peer.call with the peer ID of the destination peer. When a peer calls you, the call event is emitted.

Unlike data connections, when receiving a call event, the call must be answered or no connection is established.

// Call a peer, providing our mediaStream
var call = peer.call('dest-peer-id',
  mediaStream);

peer.on('call', function(call) {
  // Answer the call, providing our mediaStream
  call.answer(mediaStream);
});

When calling or answering a call, a MediaStream should be provided. The MediaStream represents the local video (webcam) or audio stream and can be obtained with some (browser-specific) version of navigator.getUserMedia. When answering a call, the MediaStream is optional and if none is provided then a one-way call is established. Once the call is established, its open property is set to true.

peer.call and the callback of the call event provide a MediaConnection object. The MediaConnection object itself emits a stream event whose callback includes the video/audio stream of the other peer.

call.on('stream', function(stream) {
  // `stream` is the MediaStream of the remote peer.
  // Here you'd add it to an HTML video/canvas element.
});

Read the MediaConnection API reference for complete details on its methods and events.

SkyWay Rest API

listAllPeers()

Gets a list of active PeerID's connecting with the API key.

peer.listAllPeers(function(list){
      // e.g. Add retrieved Peer ID list to userList array.
    for(var cnt = 0;cnt < list.length;cnt++){
        userList.push(list[cnt]);
    }
});

The SkyWay Rest API can only be accessed from the domain registered with the API key.

Common questions

What kind of data can I send?

PeerJS has the BinaryPack serialization format built-in. This means you can send any JSON type as well as binary Blobs and ArrayBuffers. Simply send arbitrary data and you'll get it out the other side:

conn.send({
  strings: 'hi!',
  numbers: 150,
  arrays: [1,2,3],
  evenBinary: new Blob([1,2,3]),
  andMore: {bool: true}
});

Depending on the value of serialization, the data that can be sent between each of the platforms (JavaScript, iOS, and Android) changes. See this chart for details.

Are there any caveats?

A small percentage of users are behind symmetric NATs. When two symmetric NAT users try to connect to each other, NAT traversal is impossible and no connection can be made. A workaround is to proxy through the connection through a TURN server. You'll have to find your own. If you wish to use SkyWay's TURN server, you can apply here. You can pass a TURN server into the Peer object options. This will allow your PeerJS app to work seamlessly for this situation.

How do I use a TURN server?

When creating your Peer object, pass in the ICE servers as the config key of the options hash.

var peer = new Peer({
  config: {'iceServers': [
    { url: 'stun:stun.skyway.io.com:3478' },
    { url: 'turn:homeo@turn.bistri.com:80', credential: 'homeo' }
  ]} /* Sample servers, please use appropriate ones */
});

This option doesn't need to be set if you're using SkyWay's TURN server.

What is the current state of browser compatibility?

We keep an frequently-updated catalogue of WebRTC compatibility information and caveats here.

What if my peer has not yet connected to the server when I attempt to connect to it?

When you try to connect to a peer, PeerServer will hold a connection offer for up to 5 seconds before rejecting it. This is useful if you want to reconnect to a peer as it disconnects and reconnects rapidly between web pages.

Why am I unable to connect?

You could be behind a symmetric NAT, in which case you'll need to set up a TURN server.

What about latency/bandwidth?

Data sent between the two peers do not touch any other servers except for use of turn server, so the connection speed is limited only by the upload and download rates of the two peers. This also means you don't have the additional latency of an intermediary server.

The latency to establish a connection can be split into two components: the brokering of data and the identification of clients. PeerJS has been designed to minimize the time you spend in these two areas. For brokering, data is sent through an XHR streaming request before a WebSocket connection is established, then through WebSockets. For client identification, we provide you the ability to pass in your own peer IDs, thus eliminating the RTT for retrieving an ID from the server.

More questions?

Discuss SkyWay on SkyWay Technical Forum Google Group.

Discuss PeerJS on PeerJS Google Group.

Disclaimer

This document is based on http://peerjs.com/docs/ and provides additional information necessary to use NTT Communication's SkyWay service. We cannot respond to inquiries regarding the original document.

SkyWay iOS SDK docs

SkyWay simplifies peer-to-peer data, video, and audio calls using WebRTC."SkyWay iOS SDK" is a framework that enables using SkyWay in iOS apps.This guide will show you the basic concepts of the SkyWay iOS SDK. If you learn better from seeing a working app, see the examples

Setup

1. Add required libraries and frameworks

Add the following libraries and frameworks to your Xcode project.

AudioToolbox.framework
AVFoundation.framework
CoreMedia.framework
CoreVideo.framework
VideoToolbox.framework
CoreGraphics.framework
Foundation.framework
GLKit.framework
SystemConfiguration.framework
libc++.tbd
libstdc++.6.0.9.tbd
libsqlite3.tbd
libicucore.tbd

2. Import SkyWay iOS SDK

Add SkyWay.framework to your Xcode project and import header file. Make sure you set "Linking > Other Linker Flags = -ObjC" in Build Settings.

#import <SkyWay/SKWPeer.h>

※This SDK doesn't support Bitcode because of our internal library. On Xcode7, please set "Build Options > Enable Bitcode = NO" in Build Settings.

3. Create the SKWPeer object

The SKWPeer object is where we create and receive connections.

SKWPeerOption* options = [[SKWPeerOption alloc] init];
options.key = @"{APIKEY}";
options.domain = @”{DOMAIN}”;
SKWPeer* peer = [[SKWPeer alloc] initWithOptions:options];

You can sign up for your own free key. You will need to register a domain when you sign up for an API key. You will only be able to use the API key from the registered domains.

You can also run your own PeerServer for session metadata and candidate signaling, if you don't like the cloud.

We're now ready to start making connections!

Usage

Every SKWPeer object is assigned a random, unique ID when it's created.

[peer on:SKW_PEER_EVENT_OPEN callback:^(NSObject* obj)
{
    if (YES == [obj isKindOfClass:[NSString class]])
    {
        NSString* ownId = (NSString *)obj;
    }
}];

When we want to connect to another peer, we'll need to know their peer id. Use the listAllPeers method of the SKWPeer class to get the remote PeerId or communicate PeerIds out of bound through some other method. Optionally, you can pass in your own IDs to the SKWPeer constructor.

Read the Peer API reference for complete information on its options, methods, events, and error handling.

Data connections

Start a data connection by calling connectWithId with the peer ID of the destination peer. Anytime another peer attempts to connect to your peer ID, you'll receive a SKW_PEER_EVENT_CONNECTION event.

SKWDataConnection* dataConnection = [peer connectWithId:'dest-peer-id'];

[peer on:SKW_PEER_EVENT_CONNECTION callback:^(NSObject* dataConnection){ ... }];

connectWithId method of the SKWPeer class and the callback of the SKW_PEER_EVENT_CONNECTION event will both provide a SKWDataConnection object. This object will allow you to send and receive data:

[dataConnection on:SKW_DATACONNECTION_EVENT_OPEN callback:^(NSObject* obj){ ... }];
[dataConnection on:SKW_DATACONNECTION_EVENT_DATA callback:^(NSObject* obj)
{
    // Receive String messages
    NSString* strData = nil;
    if ([obj isKindOfClass:[NSString class]])
    {
        strData = (NSString *)obj;
    }
}];
// Send messages
BOOL bResult = [dataConnection send:@"Hello SkyWay!"];
if (NO == bResult)
{
    // Failed
}
else
{
    // Succeeded
}
    

Read the DataConnection API reference for complete details on its methods and events.

Video/audio calls

Call another peer by calling callWithId with the peer ID of the destination peer. When a peer calls you, the SKW_PEER_EVENT_CALL event is emitted.

Unlike data connections, when receiving a SKW_PEER_EVENT_CALL event, the call must be answered or no connection is established.

SKWMediaConnection* mediaConnection = [peer callWithId:dest-peer-id stream:mediaStream];

[peer on:SKW_PEER_EVENT_CALL callback:^(NSObject* mediaConnection){
    [mediaConnection answer:mediaStream];
}];

When calling or answering a call, a MediaStream should be provided. MediaStream represents the local video (webcam) or audio stream and can be obtained SKWNavigator getUserMedia method. When answering a call, the MediaStream is optional and if none is provided then a one-way call is established. Once the call is established, its isOpen property is set to YES.

callWithId method of the SKWPeer class and the callback of the SKW_PEER_EVENT_CALL event provide a MediaConnection object. The MediaConnection object itself emits a SKW_MEDIACONNECTION_EVENT_STREAM event whose callback includes the video/audio stream of the other peer.

[mediaConnection on:SKW_MEDIACONNECTION_EVENT_STREAM callback:^(NSObject* stream)
{
    // `stream` is the SKWMediaStream of the remote peer.
    // Here you'd add it to SKWVideo.
}];

Read the MediaConnection API reference for complete details on its methods and events.

SkyWay RestAPI

listAllPeers

Gets a list of active PeerID's connecting with the API key.

[peer listAllPeers:^(NSArray* aryPeers)
{
    for (NSString* strPeer in aryPeers)
    {
        ...
    }
}];

The SkyWay Rest API can only be accessed from the domain registered with the API key.

FAQ

What kind of data can I send?

When serialization is set to binary or binary-utf8, MessagePack serialization format is used. You can easily send NSData*, NSString*, NSNumber*, NSDictionary*, NSArray*. It is not possible for an NSDictionary or NSArray to contain another NSDictionary/NSArray.

NSDictionary* dctData = @{
    @"1": @"one",
    @"2": @"two",
    @"3": @"three",
    @"4": @"four",
    @"5": @"five",
    };
BOOL bResult = [_dataConnection send:dctData];

Depending on the value of serialization, the data that can be sent between each of the platforms (JavaScript, iOS, and Android) changes. See this chart for details.

Are there any caveats?

A small percentage of users are behind symmetric NATs. When two symmetric NAT users try to connect to each other, NAT traversal is impossible and no connection can be made. A workaround is to proxy through the connection through a TURN server. You'll have to find your own. If you wish to use SkyWay's TURN server, you can apply here. You can pass a TURN server into the Peer object options. This will allow your PeerJS app to work seamlessly for this situation.

How do I use a TURN server?

When creating your Peer object, pass in the ICE servers as the config key of the options hash.

SKWIceConfig* configStun = [[SKWIceConfig alloc] init];
configStun.url = @"stun:stun.skyway.io:3478";

SKWIceConfig* configTurn = [[SKWIceConfig alloc] init];
configTurn.url = @"turn:homeo@turn.bistri.com:80";
configTurn.credential = @"homeo";
// Sample servers, please use appropriate ones

SKWPeerOption* options = [[SKWPeerOption alloc] init];
option.config = @[configStun,configTurn];

SKWPeer* peer = [[SKWPeer alloc] initWithOptions:options];

This option doesn't need to be set if you're using SkyWay's TURN server.

What if my peer has not yet connected to the server when I attempt to connect to it?

When you try to connect to a peer, PeerServer will hold a connection offer for up to 5 seconds before rejecting it. This is useful if you want to reconnect to a peer as it disconnects and reconnects rapidly between web pages.

Why am I unable to connect?

You could be behind a symmetric NAT, in which case you'll need to set up a TURN server.

What about latency/bandwidth?

Data sent between the two peers do not touch any other servers except for use of turn server, so the connection speed is limited only by the upload and download rates of the two peers. This also means you don't have the additional latency of an intermediary server.

The latency to establish a connection can be split into two components: the brokering of data and the identification of clients. PeerJS has been designed to minimize the time you spend in these two areas. For brokering, data is sent through an XHR streaming request before a WebSocket connection is established, then through WebSockets. For client identification, we provide you the ability to pass in your own peer IDs, thus eliminating the RTT for retrieving an ID from the server.

Supported OS

iOS 7+

Supported devices

iPhone 5+、iPodTouch 6+、iPad 2+

More questions?

Discuss SkyWay on SkyWay Technical Forum Google Group.

Disclaimer

This document is based on http://peerjs.com/docs/ and provides additional information necessary to use NTT Communication's SkyWay service. We cannot respond to inquiries regarding the original document.

SkyWay Android SDK docs

SkyWay simplifies peer-to-peer data, video, and audio calls using WebRTC."SkyWay Android SDK" is a framework that enables using SkyWay in Android apps.This guide will show you the basic concepts of the SkyWay Android SDK. If you learn better from seeing a working app,see the examples

Setup

1. Add required settings

Add the following settings to your manifest file.

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
<uses-feature android:glEsVersion="0x00020000" android:required="true" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

2. Import SkyWay Android SDK

Add SkyWay.aar to your application and import class files.

#import io.skyway.Peer.*

3. Create the Peer object

The Peer object is where we create and receive connections.

PeerOption options = new PeerOption();
options.key = "{APIKEY}";
options.domain = "{DOMAIN}";
Peer peer = new Peer(options);

You can sign up for your own free key. You will need to register a domain when you sign up for an API key. You will only be able to use the API key from the registered domains.

You can also run your own PeerServer for session metadata and candidate signaling, if you don't like the cloud.

We're now ready to start making connections!

Usage

Every Peer object is assigned a random, unique ID when it's created.

peer.on(Peer.PeerEventEnum.OPEN, new OnCallback(){
  　public void onCallback(Object object){
    　if (object instanceof String){
      　string id = (String) object;
    　}
  　}
　});

When we want to connect to another peer, we'll need to know their peer id. PeerクラスのlistAllPeers method of the SKWPeer class to get the remote PeerId or communicate PeerIds out of bound through some other method. Optionally, you can pass in your own IDs to the Peer constructor.

Read the Peer API reference for complete information on its options, methods, events, and error handling.

Data connections

Start a data connection by calling connect(peerId) with the peer ID of the destination peer. Anytime another peer attempts to connect to your peer ID, you'll receive a PeerEventEnum.CONNECTION event.

DataConnection dataConnection = peer.connect('dest-peer-id');

peer.on(Peer.PeerEventEnum.CONNECTION,new OnCallback(){
 public void onCallback(Object object){ ... }
 });

Peer connect(peerId) and the callback of the PeerEventEnum.CONNECTION event will both provide a DataConnection object. This object will allow you to send and receive data:

dataConnection.on(DataEventEnum.DATA,new OnCallback(){
  public void onCallback(Object object){
    // Receive String messages
    String strValue = null;
    if (object instanceof String){
      strValue = (String)object;
    }
  }
});

// Send messages
Bool bResult = dataConnection.send("Hello SkyWay!");
if(NO == bResult){
  // Failed
}else{
  // Succeeded
}

Read the DataConnection API reference for complete details on its methods and events.

Video/audio calls

Call another peer by calling call(peerId) with the peer ID of the destination peer. When a peer calls you, the PeerEventEnum.CALL event is emitted.

Unlike data connections, when receiving a PeerEventEnum.CALL event, the call must be answered or no connection is established.

MediaConnection mediaConnection = peer.call('dest-peer-id',mediaStream);

peer.on(Peer.PeerEventEnum.CALL,new OnCallback(){
  public void onCallback(Object object){
    mesiaConnection.answer(mesiastream);
  }
});

When calling or answering a call, a MediaStream should be provided. MediaStream represents the local video (webcam) or audio stream and can be obtained Navigator getUserMedia method. When answering a call, the MediaStream is optional and if none is provided then a one-way call is established. Once the call is established, its isOpen property is set to true.

Peer call(peerId) and the callback of the PeerEventEnum.CALL event provide a MediaConnection object. The MediaConnection object itself emits a MediaEventEnum.STREAM event whose callback includes the video/audio stream of the other peer.

mediaConnection.on(event, new OnCallback(){
        puclic void onCallback(Object object){
  // `stream` is the MediaStream of the remote peer.
  // Here you'd add it to Canvas.
        }
      });

Read the MediaConnection API reference for complete details on its methods and events.

SkyWay RestAPI

listAllPeers

Gets a list of active PeerID's connecting with the API key.

peer.listAllPeers(new OnCallback(){
  public void onCallback(Object object){
    if (!(object instanceof JSONArray)){
      return;
    }
    JSONArray peers = (JSONArray) object;
  }
});

The SkyWay Rest API can only be accessed from the domain registered with the API key.

FAQ

What kind of data can I send?

When serialization is set to binary or binary-utf8, MessagePack serialization format is used. You can use Byte, Short, Integer, Long, Float, Double, byte[], String, ByteBuffer, List, Map. It is not possible for a Map or List to contain another Map or List.

HashMap< String, String > map = new HashMap<>();
for (int i = 0 ; 5 > i ; i++){
    String strKey = String.format("%d", i);
    String strValue = String.format("Value:%d", i);
    map.put(strKey, strValue);
  }
Boolean bResult = _data.send(map);

Depending on the value of serialization, the data that can be sent between each of the platforms (JavaScript, iOS, and Android) changes. See this chart for details.

Are there any caveats?

A small percentage of users are behind symmetric NATs. When two symmetric NAT users try to connect to each other, NAT traversal is impossible and no connection can be made. A workaround is to proxy through the connection through a TURN server. You'll have to find your own. If you wish to use SkyWay's TURN server, you can apply here. You can pass a TURN server into the Peer object options. This will allow your PeerJS app to work seamlessly for this situation.

How do I use a TURN server?

When creating your Peer object, pass in the ICE servers as the config key of the options hash.

PeerOption options = new PeerOption();

// Sample servers, please use appropriate ones
IceConfig configTurn = new IceConfig();
configTurn.url = "turn:homeo@turn.bistri.com:80";
configTurn.credential = "homeo";
options.config = {configStun,configTurn};

Peer peer = new Peer(options);

This option doesn't need to be set if you're using SkyWay's TURN server.

What if my peer has not yet connected to the server when I attempt to connect to it?

When you try to connect to a peer, PeerServer will hold a connection offer for up to 5 seconds before rejecting it. This is useful if you want to reconnect to a peer as it disconnects and reconnects rapidly between web pages.

Why am I unable to connect?

You could be behind a symmetric NAT, in which case you'll need to set up a TURN server.

What about latency/bandwidth?

Data sent between the two peers do not touch any other servers except for use of turn server, so the connection speed is limited only by the upload and download rates of the two peers. This also means you don't have the additional latency of an intermediary server.

The latency to establish a connection can be split into two components: the brokering of data and the identification of clients. PeerJS has been designed to minimize the time you spend in these two areas. For brokering, data is sent through an XHR streaming request before a WebSocket connection is established, then through WebSockets. For client identification, we provide you the ability to pass in your own peer IDs, thus eliminating the RTT for retrieving an ID from the server.

Supported OS

Android 4.0.3+

Supported devices

Nexus 5 2013、Nexus 6 2015、Xperia Z1 2013、ZenPhone 2014、Galaxy S5

More questions?

Discuss SkyWay on SkyWay Technical Forum Google Group.

Disclaimer

This document is based on http://peerjs.com/docs/ and provides additional information necessary to use NTT Communication's SkyWay service. We cannot respond to inquiries regarding the original document.