Getting Started

Wiki ▸ Getting Started

Introduction

This tutorial assumes that you've successfully installed the PhoneRTC plugin, and have working TURN and signaling servers.

If you didn't, please follow the instructions in the Installation page.

Creating Sessions

PhoneRTC's most basic concept is the Session - a connection between exactly 2 users. All voice calls, video calls and even group calls work with Sessions.

To start a new session, you'll first need to create a new Session object in both users. Here's an example of creating a Session object:

var config = {
    isInitiator: true,
    turn: {
        host: 'turn:turn.example.com:3478',
        username: 'test',
        password: '123'
    },
    streams: {
        audio: true,
        video: false
    }
}

var session = new cordova.plugins.phonertc.Session(config);

A brief summary of the config properties:

• The isInitiator property determines whether or not the current client is the caller or the callee. Basically, if you have two users, one should have isInitiator = true and the other should have isInitiator = false.

• The turn property represents the details for your TURN server.

• The streams.audio property determines whether or not the current user sends his local audio track (microphone output) to the other user. Same for streams.video.

Session Event Handling

The next step is to handle the Session's events. The first, and the most important event we'll handle is the sendMessage event:

session.on('sendMessage', function (data) { 
    signaling.send(otherUser, data);
});

The sendMessage event is called by PhoneRTC when it wants to send a message to the other client. You don't care about the content of these messages, you just need to provide a way to transmit them.

Note that data is a JSON object. You can use JSON.stringify to turn it into a string.

When you receive a new message from the other client, use the session.receiveMessage method to notify PhoneRTC. For example:

signaling.onMessage = function (message) {
    session.receiveMessage(message);
};

Note that receiveMessage accepts a JSON object, not a string. You can use JSON.parse to turn the string into an object.

We'll also handle the answer and disconnect events:

session.on('answer', function () { 
    console.log('Other client answered!');
});

session.on('disconnect', function () { 
    console.log('Other client disconnected!');
});

Initializing the call

After we've created a new session, configured it, and handled its events - we can now actually start the call.

session.call();

Note: The callee (isInitiator = false) must use the call function before the caller (isInitiator = true).

Right now, you should have a working voice chat.

Adding Video

To add a video, we need to first make a container for it. A simple <div> should be enough:

<div id="videoContainer"></div>

Make sure to make it square with fixed width and height:

#videoContainer {
    width: 300px;
    height: 300px;
    background-color: #000;
}

Now we need to let PhoneRTC know of our new video container. Before starting any call, use the phonertc.setVideoView method:

phonertc.setVideoView({
    container: document.getElementById('videoContainer'),
    local: {
        position: [0, 0],
        size: [100, 100]
    }
});

The local property lets you configure the local video size and position. You can omit it if you don't want local video view, it's optional.

Note that the setVideoView is global and not related to any Session. This fact will be useful later on for group calls.

Make sure to change streams.video in the Session config to true, and you should have a working video chat!

Group Calls

In PhoneRTC, group calls work by creating multiple sessions. Let's assume we have a group call between 3 users: A, B, C.

• User A has a session to B and a session to C
• User B has a session to A and a session to C
• User C has a session to A and a session to B

So there isn't really anything new here. When the group admin (or whatever) adds a new user to the group call, he needs to do 3 things:

1. Send a message to the new user with a list of the existing users (including himself)
2. Send a message to the existing users with the details of the new user
3. Create a new session between himself and the new user

The new user who receives the existing users list needs to start a session with each one of them, and each of the existing users needs to start a session with the new user. That's it!

One thing to note is that the video view would be automatically divided between all the users.