README.md

🎉 100ms RoomKit SDK ＆ Sample App 🚀

RoomKit SDK for iOS enables you to integrate our production-ready conferencing and livestreaming UI into your own app effortlessly. This README will guide you through the integration process and provide examples of common use cases.

Pre-requisites

• 100ms account: You will need a 100ms account to create rooms and generate tokens. If you don't have one yet, you can create it here. Once you've created an account, navigate to the 100ms dashboard and generate room-codes and auth-tokens following the provided guides.
• Xcode 14 or higher: This is required for building iOS applications.
• iOS 15 or higher: Ensure your device or simulator is running this version or higher.
• NSMicrophoneUsageDescription: You need to provide a valid description for microphone usage in your app's info.plist file.
• NSCameraUsageDescription: Similar to the microphone, you need to provide a valid description for camera usage in your app's info.plist file.

👀 To see an example app implementation of a conferencing/livestreaming app using 100ms RoomKit SDK, checkout the example repository.

To experience the example app made using RoomKit, you can download the app from TestFlight to your iOS device here: https://testflight.apple.com/join/Pb4aTS0t

Integration

You can integrate RoomKit SDK into your project using Swift Package Manager (SPM). Follow these steps:

1. Open your Xcode project.
2. Navigate to File > Add Package Dependency.
3. In the dialog that appears, enter the following URL as the package source: https://github.com/100mslive/100ms-roomkit-ios.git
4. Click Next and follow the prompts to add the package to your project.

RoomKit Basics

Import SDK

You import the RoomKit SDK with following import statement

import HMSRoomKit

Instantiate HMSPrebuiltView

You use SwiftUI view called HMSPrebuiltView to instantiate a production-ready conferencing and livestreaming UI. You can either pass a room-code or an auth-token to HMSPrebuiltView.

Initialize HMSPrebuiltView with a room code

// Initialize with room code
HMSPrebuiltView(roomCode: /*pass room code as string here*/)

Initialize HMSPrebuiltView with an auth token

// Initialize with auth token
HMSPrebuiltView(token: /*pass role's auth token as string here*/)

Example usage

Fully Featured Conferencing/Livestreaming App with Room Code

To create a fully-featured conferencing/Livestreaming app with just a room code for a role, use the following code snippet. Make sure to pass a valid room code as a string:

import SwiftUI
import HMSRoomKit

struct ContentView: View {
    var body: some View {
        HMSPrebuiltView(roomCode: /*pass room code as string here*/)
    }
}

Fully Featured Conferencing/Livestreaming App with Auth Token

To create a fully-featured conferencing/Livestreaming app with just an Auth Token for a role, use the following code snippet. Pass the role's auth token as a string:

import SwiftUI
import HMSRoomKit

struct ContentView: View {
    var body: some View {
        HMSPrebuiltView(token: /*pass role's auth token as string here*/)
    }
}

Following demo video shows you how to integrate RoomKit SDK in your app by follwing instructions above

Adding Screen Sharing Feature

To add screen sharing to your app that uses Prebuilt, follow these steps:

1. Use the code snippet below, replacing the placeholders with your App Group ID and Broadcast Upload Extension's bundle ID:

import SwiftUI
import HMSRoomKit

struct ContentView: View {
    var body: some View {
        HMSPrebuiltView(roomCode: "qsw-mik-seb")
          .screenShare(appGroupName: "group.live.100ms.videoapp.roomkit", screenShareBroadcastExtensionBundleId: "live.100ms.videoapp.roomkit.Screenshare")
    }
}

2. Ensure you have set up a broadcast upload extension target in your app and connected it with 100ms-ios-broadcast-sdk. For detailed instructions, refer to this guide.

Showing Prebuilt Screen Conditionally

To conditionally display the Prebuilt Screen from other views in your app, use the following code snippet:

import SwiftUI
import HMSRoomKit

struct ContentView: View {
    
    @State var roomCode = ""
    @State var isMeetingViewPresented = false
    
    var body: some View {
        
        if isMeetingViewPresented && !roomCode.isEmpty {
            
            HMSPrebuiltView(roomCode: roomCode, onDismiss: {
                isMeetingViewPresented = false
            })
        }
        else {
            VStack {
                TextField("Enter Room Code", text: $roomCode)
                Button {
                    isMeetingViewPresented.toggle()
                } label: {
                    Text("Join")
                }
            }
        }
    }
}

This code allows you to conditionally display the Prebuilt Screen based on user input.

How to make changes, debug, preview and contribute to RoomKit

1. Clone https://github.com/100mslive/100ms-roomkit-ios, https://github.com/100mslive/100ms-roomkit-models-ios and https://github.com/100mslive/100ms-roomkit-example in same folder.
2. Open HMSRoomKitDevelopmentProject Xcode project inside 100ms-roomkit-example repo.

3. In HMSRoomKitDevelopmentProject Xcode project, use HMSRoomKitDevelopment target scheme to run the app in simulator or device. Use HMSRoomKitPreview target to see SwiftUI preview of files under HMSRoomKit folder (HMSRoomKit source files).

5. Before making changes, drag and drop local instances of 100ms-roomkit-ios and 100ms-roomkit-models-ios repo to Xcode so that development project uses editable version of the local SPM repo. You can make changes to files in HMSRoomKit folder (HMSRoomKit source files) or HMSRoomModels folder (HMSRoomModels source files) to add a feature/improvement or fix any issue.

7. Once you are done, create PRs with your changes to main branch of respective repos.