RoomKit
  • iOS : Objective-C
  • Android
  • macOS
  • Windows
  • Web
  • Introduction
  • Demo app
  • Sample codes
  • Client SDKs
    • SDK downloads
    • Release notes
  • Getting started
    • Integration
    • Start a room
  • Guides
    • Customize room parameters
    • Customize the room UI
    • Listen for room callbacks
    • Screen rotation support
    • Screen sharing
    • Manage rooms with Education Cloud Service
    • Use server event callbacks
  • Server APIs
  • Error codes
  • API Documents
  • FAQ

Start a room

Last updated:2022-03-22 13:06

Introduction

RoomKit provides different system integration solutions for different cases:

  1. If your application already has a user management system and room (channel, group) management system, you can use your existing systems to manage user IDs and room IDs.
  2. If your application doesn't have a room (channel, group) management system, you can integrate ZEGO's Education Cloud Service to manage rooms. For detailed integration instructions, see Manage rooms with Education Cloud Service.

This document describes the implementation process based on the first scenario.

The system architecture:

/Pics/RoomKit/AllPlatform/roomkit_architecture_en.png

In this system architecture, the following components need to be implemented by yourself:

  1. The component that manages users and sends user IDs to the app clients for joining rooms.
  2. The component that manages rooms and sends room IDs to the app clients for joining rooms.
  3. The component that handles authentication tokens. To ensure system security, we recommend that you request the SDK access token from the RoomKit server through your business server and then your business server passes the tokens to your app clients for joining rooms.

Prerequisites

Before you begin, make sure you complete the following steps:

  1. Contact ZEGO Sales to enable the RoomKit service and obtain your RoomKit Admin Console login account and password.
  2. Log in to RoomKit Admin Console to obtain the SecretID, SecretSign, and ProductID, which are required for initializing the RoomKit SDK.
  3. Integrate the RoomKit SDK into your project. For details, see Quick starts - Integration.

Implementation steps

The following flowchart shows the major steps to access the RoomKit service from your app client:

/Pics/RoomKit/AllPlatform/RoomKit_edu_api_en.png

Initialize the SDK

You need to initialize the RoomKit SDK before using it.

  1. Create a ZegoInitConfig object with the SecretID you get from the RoomKit Admin Console.
  2. Call the initWithConfig method initialize the SDK with the configuration object created in the above step.
@interface ZegoInitConfig : NSObject

/// The SecretID is assigned by ZEGO
@property (nonatomic, assign) NSInteger secretID;

@end
// Create a ZegoInitConfig instance
ZegoInitConfig *config = [[ZegoInitConfig alloc] init];
config.secretID = 123456; // Use the SecretID you get from RoomKit Admin Console

// Initialize the SDK
[[ZegoRoomKit sharedInstance] initWithConfig:config completion:^(ZegoRoomKitError error) {

}];

Obtain the SDK access token

Call the RoomKit server API Get SDK acess token to obtain the SDK access token, which is required for your app client to access the RoomKit service.

  • Get the values of the request parameters secret_id and secret_sign from RoomKit Admin Console.
  • Get the value of the request parameter device_id by calling the deviceID method.

To ensure system security, we recommend that you request the SDK access token from the RoomKit server through your business server.

Set the language of UI(Optional)

You can set the language of room UI before join a room.

  1. Create a ZegoJoinRoomUIConfig object with the language setting.
  2. Call the setUIConfig ethod to set up the UI with the configuration object created above.
// Create and initialize a ZegoJoinRoomUIConfig object with language settings
ZegoJoinRoomUIConfig *uiconfig = [ZegoJoinRoomUIConfig new];
uiconfig.language = 2; // 2 for English

// Set up the UI using the above configuration
[[ZegoRoomKit sharedInstance].inRoomService setUIConfig:uiconfig];

Join a room

To join a room, you need the following information:

  • Authentication information: token, productID
  • Room information: roomID
  • User information: userID, userName, role

The user IDs and room IDs can be any 64-bit numeric values. But, you need to ensure user IDs and room IDs are unique within the scope of your project. Otherwise, data may get mixed up and users who share the same userID will kick out each other.

  1. Create a ZegoJoinRoomConfig object with the above information.
  2. Call the joinRoomWithConfig method to join the room with the configuration object created in the above step.
/// Configuration for joining a room 
///
@interface ZegoJoinRoomConfig : NSObject

/// Room ID
@property (nonatomic, copy) NSString *roomID;

/// Project ID
@property (nonatomic, assign) NSInteger productID;

/// SDK authentication token
@property (nonatomic, copy) NSString *token;

/// User name
@property (nonatomic, copy) NSString *userName;

/// User ID
@property (nonatomic, assign) NSInteger userID;

/// User role
@property (nonatomic, assign) ZegoRoomKitRole role;

@end
// Create a configuration object
ZegoJoinRoomConfig *config = [ZegoJoinRoomConfig new];
config.roomID = @"123456789"; // Room ID
config.productID = 1234; // productID
config.userName = @"Anne"; // User name
config.userID = 123456789; // User ID
config.role = ZegoRoomKitRoleAttendee; // Join the room as an attendee
config.token = @"qwertyuiop"; // The SDK token obtained by calling the corresponding Server API

// Join the room
[[ZegoRoomKit sharedInstance].inRoomService joinRoomWithConfig:config
                                                        fromVC:fromVC
                                                    completion:^(ZegoRoomKitError errorCode) {
}];