Skip to main content
Version: 5.4

Implement your first group video call

WebPlanetKit lets you integrate audio and video call functionality for 1-to-1 calls or group calls into your app. This guide shows how to get started with the implementation of a group video call in your web app.

Note

For faster development, you can implement your app on top of our quick start.

Prerequisites​

Install the SDK​

WebPlanetKit SDK can be installed in two ways.

Note

WebPlanetKit provides different library files depending on the development environment. Use planetKit.eval.js for the evaluation environment and planetKit.js for the real environment.

Install using npm or yarn​

Install the SDK using npm or Yarn as follows.

# npm
npm install @line/planet-kit

# yarn
yarn add @line/planet-kit

After installation, use the SDK according to the environment you are using.

  • For the real environment

    import * as PlanetKit from "@line/planet-kit";

  • For the evaluation environment

    import * as PlanetKit from "@line/planet-kit/dist/planet-kit-eval";

Download from Git and include with a <script> tag​

Instead of installing via npm or Yarn, you can also directly include the WebPlanetKit SDK in your code by downloading it from the Git repository's dist directory and using a <script> tag.

Download the file appropriate for your environment and include the SDK in your code with a <script> tag as follows.

  • For the real environment

    <script type="text/javascript" src="path/to/js/planet-kit.js"></script>

  • For the evaluation environment

    <script type="text/javascript" src="path/to/js/planet-kit-eval.js"></script>

After including the SDK as above, use it as follows.

<script type="text/javascript">
  const planetKit = new PlanetKit.Conference();
</script>

Initialize the SDK​

To call the WebPlanetKit API, you must initialize the SDK first. WebPlanetKit has two instances: one for 1-to-1 calls and another for group calls (conferences). Each instance is created by calling PlanetKit.Call() and PlanetKit.Conference() with configuration information, and you can also set the appropriate log level at this time.

For group calls, initialize the SDK as follows.

import * as PlanetKit from "@line/planet-kit";

const config = {
  logLevel: 'log'
}
const planetKit = new PlanetKit.Conference(config);

Get the access token​

In the client app, request your app server to generate an access token and get the generated access token.

Note

You must get a new access token and use it each time you call joinConference() to participate in a group video call.

Join a group video call​

To join a group video call, call joinConference() with the following argument:

  • ConferenceParams object containing the following properties:
    • myId: User ID of the local user
    • myServiceId: Service ID of the local user
    • roomId: Room ID
    • roomServiceId: Service ID of the room
    • accessToken: Access token
    • mediaType: 'video'
    • mediaHtmlElement: DOM element for playing media
      • myVideo: <video> element where the video will be played
      • roomAudio: <audio> element where the audio will be played
    • delegate: Event delegate complying with ConferenceDelegate
      • evtConnected: Event that occurs when the call is connected
      • evtDisconnected: Event that occurs when the call is disconnected
      • evtPeerListUpdated: Event that occurs when peers enter or leave the room
      • evtPeersVideoUpdated: Event that occurs when a peer's video is enabled or disabled
<!-- Example of media elements for group video call -->
<html>
    <div>
        <video id="my-video" muted autoplay playsinline></video>
        <audio id="room-audio" autoplay></audio>
    </div>
</html>

<script>
    const myVideoElement = document.getElementById('my-video');
    const roomAudioElement = document.getElementById('room-audio');
</script>
/* Prepares a conferenceParams */
const onEvtConnected = () => {
    // This is called when the call is connected.
    // Write your own code here.
};

const onEvtDisconnected = (disconnectedParam) => {
    // This is called when the call is disconnected.
    // Write your own code here.
};

const onEvtPeerListUpdated = (conferencePeerUpdatedParam) => {
    // This is called when the list of peers is updated.
    // Write your own code here.
};

const onEvtPeersVideoUpdated = (peersVideoUpdatedParam) => {
    // Triggered when the video status of one or more peers are changed.
    // Write your own code here.
};

const conferenceParams = {
    myId: 'MY_ID',
    myServiceId: 'MY_SERVICE_ID',
    roomId: 'ROOM_ID',
    roomServiceId: 'ROOM_SERVICE_ID',
    accessToken: 'ACCESS_TOKEN',
    mediaType: 'video',
    mediaHtmlElement: {
        myVideo: myVideoElement,
        roomAudio: roomAudioElement
    },
    delegate: {
        evtConnected: onEvtConnected,
        evtDisconnected: onEvtDisconnected,
        evtPeerListUpdated: onEvtPeerListUpdated,
        evtPeersVideoUpdated: onEvtPeersVideoUpdated
    }
};

/* Joins conference */
planetKit.joinConference(conferenceParams)
    .then(() => {
        // Successfully joined a conference.
    })
    .catch((joinConferenceError) => {
        // Failed to join a conference.
        // joinConferenceError.reason: START_FAIL_REASON
        // joinConferenceError.message: A descriptive message about the failure.
    });
Note
  • Users need the room ID to enter the room from the client app, so the room ID must be shared with other users through an application-defined communication channel.
  • When a call is connected, the web browser will display a pop-up requesting microphone and camera permissions, and the user must grant permissions for the call to proceed.

Request and remove video for a peer​

To request video for a peer, call requestPeerVideo with the ConferenceRequestPeerVideoParams object. To remove video for a peer, call removePeerVideo with the userId.

The following example shows how to request or remove video for a peer in the event handler when the peer enters or leaves the room and an event occurs.

<!-- Example of peer's video element -->
<html>
    <div>
        <video id="peer-video-1" muted autoplay playsinline></video>
    </div>
</html>
function requestPeerVideo(userId) {
    const requestPeerVideoParams = {
        userId: userId,
        resolution: 'vga',
        videoViewElement: document.getElementById('peer-video-1')
    };

    planetKit.requestPeerVideo(requestPeerVideoParams)
    .then(() => {
        // Peer video requested successfully.
    })
    .catch((error) => {
        // Failed to request peer video.
    });
}

function removePeerVideo(userId) {
    planetKit.removePeerVideo(userId)
    .then(() => {
        // Peer video removed successfully.
    })
    .catch((error) => {
        // Failed to remove peer video.
    });
}

// Called when the list of peers is updated.
// This handler is registered as the delegate of conferenceParams.
const onEvtPeerListUpdated = (conferencePeerUpdatedParam) => {
    const { addedPeers, removedPeers } = conferencePeerUpdatedParam;

    // Request video for newly added peers.
    addedPeers.forEach((peerInfo) => {
        if (peerInfo.videoState === VIDEO_STATE.ENABLED) {
            requestPeerVideo(peerInfo.userId);
        }
    });

    // Remove video for peers that left.
    removedPeers.forEach((peerInfo) => {
        if (peerInfo.videoRequested) {
            removePeerVideo(peerInfo.userId);
        }
    });
};

Next steps​

See the following documents to learn more about the various features provided by WebPlanetKit and how to use each feature.

  • Call flow: Familiarize yourself with the call flow for each call type.
  • Extended functions: Explore the guides on extended functions, such as screen share and media statistics.
  • Code examples: See the code examples that you can use for implementing your own app.
  • Reference: Refer to the API reference, API changelog, and release notes.