Implement your first group video call

PlanetKit 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 macOS app.

Note

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

Prerequisites

• Make sure that your system meets the system requirements.
• Create an API key. For more information, see Development environment.
• Implement app server code to generate an access token. For more information, see How to generate access tokens.
• Install Xcode 16 or higher.

Create a project

To get started, open Xcode and create a new project as follows:

1. Click Create a new Xcode Project in the Welcome to Xcode window.
2. In macOS tab, select App and click Next.
3. In the project creation window, do the following.
   1. Enter your product name in the Product Name field.
   2. Select your development team in the Team field.
   3. Enter the organization identifier in the Organization Identifier field.
   4. Select Storyboard in the Interface field.
   5. Click Next.
4. Select the location where your project will be created, and click Create.

Install the SDK

Install the SDK through Swift Package Manager.

1. Select File > Add Packages... in the Xcode menu bar.
2. Enter the PlanetKit repository URL (https://github.com/line/planet-kit-apple) in the Search or Enter Package URL field.
3. Click the Add Package button.

Request system permissions

To enable video call functionality, users need to grant your app the permission to access the microphone and camera. To make that procedure happen, perform the following:

• Add the NSMicrophoneUsageDescription and NSCameraUsageDescription keys to your app's Info.plist file.

  

• Enable the following App Sandbox entitlements in Signing & Capabilities for your app target.

  • Incoming Connections (Server) and Outgoing Connections (Client) under Network
  • Camera and Audio Input under Hardware

  

Initialize the SDK

To call the PlanetKit APIs, you must initialize PlanetKit first. Initialize PlanetKit using initialize() of PlanetKitManager with a PlanetKitInitialSettingBuilder object.

You must set the server URL (planet_base_url) in the PlanetKitInitialSettingBuilder object when calling initialize(). Make sure that you use an appropriate planet_base_url depending on the development environment that you're using.

// AppDelegate.swift

// Import PlanetKit SDK
import PlanetKit

PlanetKitManager.shared.initialize(initialSettings: PlanetKitInitialSettingBuilder()
    .withSetKitServerKey(serverUrl: planet_base_url)
    .build())

Note

The initialize() method must be called once initially in your app. It is recommended to initialize the SDK in the applicationDidFinishLaunching(_:) method of your AppDelegate that adopts and conforms to NSApplicationDelegate.

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().

Join a group video call

To join a group video call, call joinConference() of PlanetKitManager with a PlanetKitConferenceParam object that includes the following properties:

• myUserId: Local user's user ID
• roomId: Room ID
• roomServiceId: Room service ID
• delegate: Event delegate that adopts and conforms to PlanetKitConferenceDelegate
• mediaType: Set to .audiovideo for a video call
• accessToken: Access token

import PlanetKit

class YourClass {
    func joinConference() {
        let param = PlanetKitConferenceParam(myUserId: myUserId, roomId: roomId, roomServiceId: serviceId, displayName: nil, delegate: self, accessToken: accessToken)
        param.mediaType = .audiovideo
        let result = PlanetKitManager.shared.joinConference(param: param, settings: nil)

        if (result.reason == PlanetKitStartFailReason.none && result.conference != null) {
            // The "result.conference" instance is the main instance to call APIs from now on.
            // You must keep it to control this call.
        }
        else {
            // Handle an error by referring to result.reason.
        }
    }
}

extension YourClass: PlanetKitConferenceDelegate {
    func didConnect(_ conference: PlanetKitConference, connected: PlanetKitConferenceConnectedParam) {
        // This is called when the call is connected.
        // Write your own code here.
    }

    func didDisconnect(_ conference: PlanetKitConference, disconnected: PlanetKitDisconnectedParam) {
        // This is called when the call is disconnected.
        // Write your own code here.
    }

    func peerListDidUpdate(_ conference: PlanetKitConference, updated: PlanetKitConferencePeerListUpdateParam) {
        // This is called when the list of peers is updated.
        // Write your own code here.
    }

    func peersVideoDidUpdate(_ conference: PlanetKitConference, updated: PlanetKitConferenceVideoUpdateParam) {
        // This is called when the video of one or more peers is updated.
        // Write your own code here.
    }
}

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.

Add a video view for the local user

To add a video view for the local user, create a PlanetKitMTKView (myVideoView), add it as a subview to the local view, and set it as the camera preview's video stream delegate using startPreview(delegate:).

class YourViewController: NSViewController {
    ...

    private var myVideoView: PlanetKitMTKView = {
        PlanetKitMTKView(frame: .zero, device: nil)
    }()

    override func viewDidLoad() {
        super.viewDidLoad()

        view.addSubview(myVideoView)
        PlanetKitCameraManager.shared.startPreview(delegate: myVideoView)
    }

    override func viewDidDisappear() {
        super.viewDidDisappear()

        PlanetKitCameraManager.shared.stopPreview(delegate: myVideoView)
    }
}

Add a video view for a peer

To add a video view for a peer, create a PlanetKitMTKView (peerVideoView) and add it as a subview to the peer view.

class YourViewController: NSViewController {
    ...

    private var peerVideoView: PlanetKitMTKView = {
        PlanetKitMTKView(frame: .zero, device: nil)
    }()

    override func viewDidLoad() {
        super.viewDidLoad()

        view.addSubview(peerVideoView)
    }
}

Create peer control for each peer

When the peer list is updated, create PlanetKitPeerControl for newly added peers and register a PlanetKitPeerControlDelegate object. You can handle the status change of each peer using the PlanetKitPeerControlDelegate.

class YourViewController: NSViewController {
    ...
    private var peerControl: PlanetKitPeerControl?

    private func showPeerVideo(_ peerId: String) {
        guard let peer = conference.getPeer(peerId: PlanetKitUserId(id: peerId, serviceId: serviceId)) else {
            // Handle an error by getting a peer instance.
            return
        }
        guard let peerControl = conference.createPeerControl(peer: peer) else {
            // Handle an error by creating peer control.
            return
        }
        self.peerControl = peerControl

        peerControl.register(self) { success in
            guard success else {
                // Handle an error by registering peer control.
                return
            }
            peerControl.startVideo(maxResolution: .recommended, delegate: self.peerVideoView) { success in
                if !success {
                    // Handle an error by starting video.
                }
            }
        }
    }
}

Next steps

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

• Call flow: Familiarize yourself with the call flow for each call type.
• Subgroup: Read the guides on subgroups, which allows you to implement advanced features such as multi-subgroup rooms or translation rooms.
• Extended functions: Explore the guides on extended functions, such as screen share and data sessions.
• 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.