Live iOS v1
Live iOS
Live
iOS
Home
/
Live
/
iOS

Sendbird Live Beta for iOS

With Sendbird Live beta SDK, you can integrate live streaming functionality where users can host and participate in live events. In a live event, hosts can communicate with real-time voice and video while participants can engage in a live event by using chat, which is built on open channels from Sendbird Chat.

This document explains how you can implement Sendbird Live beta SDK to your app and how users can host or participate in a live event. For details of the SDK interface comprising the Live beta SDK, refer to the API reference.

Note: This documentation is intended for customers participating in the Sendbird Live beta program, launched on September 15th, 2022.


Authentication

In order to use Sendbird Live beta SDK in the client app, initialize the SDK with your Sendbird application ID when you first launch the client app. You can find your application ID on Sendbird Dashboard.

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        SendbirdLive.initialize(applicationId: "APPLICATION_ID")
        ..
    }
}

Once you’ve authenticated the client app, authenticate a user by calling the SendbirdLive.authenticate() method. Calling this method also authenticates the user with Sendbird Chat SDK which provides the chat functionality during a live event.

func signIn(userId: String, accessToken: String?) {
    SendbirdLive.authenticate(userId: userId, accessToken: accessToken) { result in
        switch result {
        case .success(let user):
            // User is successfully created.
        case .failure(let error):
            // Error occurred during authentication.
        }
    }
}

Host a live event

A live event can be created using the Live beta SDK instantly or in advance of the schedule. Once a live event has been created, one of the users you set to act as host can run the event. The available live event states are: created, ready, ongoing, and ended. Participants can enter live events in ready or ongoing states.

Create a live event

The first step is to configure the live event by providing a LiveEventConfiguration object. You can provide some basic information related to the event such as the title and the cover image that would show on the thumbnail. If not specified, the live event ID will show as the title and the thumbnail will show as black.

A live event requires a host for which you can provide candidates in the userIdsForHost property. Up to ten users can be set as candidates and only one of them can act as a host for the live event. When an incumbent host exits, any other users specified in userIdsForHost can enter the live event and act as a host.

Once you have configured the LiveEvent object, you can create a live event by calling the SendbirdLive.createLiveEvent method. If the creation was successful, the status of the live event will be created and an open channel will be available in which the host can chat.

In case the open channel isn’t available, call fetchOpenChannel() to fetch the open channel.

func createLiveEvent() {
    let config = LiveEvent.Configuration(
        userIdsForHost: [currentUser.userId],
        title: "New Event",
        thumbnail: coverImageURL
    )
    SendbirdLive.createLiveEvent(config: config) { result in
        switch result {
        case .success(let liveEvent):
            // A live event is successfully created.
        case .failure(let error):
            // Error occurred while creating a live event.        }
    }
}

Enter a live event

Once the host has entered the live event, the host can exit, re-enter, start and end their media stream, and change the state of the event. The host can also chat in the open channel.

Note: The actions that the host can take are independent of the states of the live event. The host can exit the live event without ending the live event because endEvent() must be called to end the live event. For further detail, refer to leave the live event temporarily.

liveEvent.enterAsHost { error in
    guard error == nil else { return }
    // Successfully entered the live event.
}

liveEvent.exitAsHost { error in
    guard error == nil else { return }
    // Successfully exited the live event.
}

Check the settings of a live event

The host can view their own media stream before changing the state to ready and allow participants to enter. The host can specify audio and video devices by using the selectVideoDevice() and selectAudioDevice() methods and call liveEvent.setVideoViewForLiveEvent(videoView, hostId: hostId). When the devices are not specified, the screen will be black without any audio. Then, the host can establish a connection with the Sendbird server by calling the startStreaming() method to see their own view.

liveEvent.setVideoViewForLiveEvent(videoView, hostId: hostId)

liveEvent.startStreaming()

Change the state of a live event

Before starting the event, the host can change the state to ready by calling the setEventReady() method. This action will allow participants to enter the event and chat among themselves or with the host. At this point, the participants can’t receive the host’s media streaming yet.

liveEvent.setEventReady {  }

Start a live event

The host can start the live event by calling startEvent() as shown below. When the live event starts, participants can receive the media stream to watch and listen to the host.

liveEvent.startEvent { }

The liveEvent.startStreaming() method will be implicitly called within the Live beta SDK to establish the connection with the Sendbird server and stream media if the host hadn’t streamed media in check the settings of a live event. If the host had called the liveEvent.startStreaming() to test media streaming earlier, the connection established from then will be used.

Displaying the host view

During the live event, the host’s media will be streamed using the video devices that are specified in the selectVideoDevice() method.

For the host to view their own media stream, the host is required to specify the video view by calling the liveEvent.setVideoViewForLiveEvent(view:hostId:) method. For the best experience, here are some components included in the SDK that you can use in creating the host view.

Note: It is recommended to set up the host view before starting the live event so participants can readily receive the host’s media streaming when they enter the live event.

Manage media during a live event

Once the host starts the live event by calling the startEvent() method, the state changes to ongoing. While the live event is ongoing, the host can perform various actions to manage media such as turning on or off their audio and video, and switching the audio and video source.

// The user must be a host in order to control the media of the live event.
guard liveEvent.myRole == .host else { return }

// Mute audio input.
liveEvent.muteAudioInput { error in
   guard error == nil else { return }
}

// Unmute audio output.
liveEvent.unmuteAudioInput { error in
   guard error == nil else { return }
}

// Start video.
liveEvent.startVideo { error in
   guard error == nil else { return }
}

// Stop video.
liveEvent.stopVideo { error in
   guard error == nil else { return }
}

// Switch to a different camera.
liveEvent.switchCamera { error in
   guard error == nil else { return }
}

Leave the live event temporarily

The host can also exit and re-enter the event without ending the live event. When the host exits the live event without explicitly calling endEvent(), the participants can continue to chat among themselves but they will see a black view and won’t hear any audio. Calling the liveEvent.stopStreaming() yields the same result.

End a live event

To end a live event, call liveEvent.endEvent(). When you end the live event, the host’s media streaming will stop, the chat will freeze, and all participants will be forced out of the live event.

When the host ends the live event, LiveEventDelegate.didLiveEventEnd(_:) will be invoked which can be used to let the participants know that the live event has ended.


Participate in a live event

A user can search and enter a live event they would like to watch. Each time the user re-enters the same event from a device, the user is counted as a new participant and up to 10,000 participants are allowed to enter the live event simultaneously.

Get a list of live events

A user can get a list of ongoing events by using the LiveEventListQuery object. The user can filter their search by creation date, participant count, duration, live event ID and more by using the LiveEventListQueryParams object. If the user knows the URL of the live event, the user can directly find the live event by using SendbirdLive.getLiveEvent(id:completionHandler:).

var params = LiveEventListQueryParams()
params.limit = 10
params.participantCountRange = 10..<1000
let query = SendbirdLive.createLiveEventListQuery(params: params)
query.next { liveEvents, error in
    guard error == nil else { return }
    // Show the list of live events to users in a list view.
}

An open channel should be available when a live event is retrieved. In case the open channel isn’t available, call fetchOpenChannel() to fetch the open channel.

Enter a live event

A user can enter any live events that are in ready or ongoing states by calling liveEvent.enter(). When a user enters a live event, the user is counted as a participant.

When a user enters a live event that is ready, they can chat but can’t watch the event yet because the host’s media stream isn’t available to them. When users enter an ongoing live event, they can chat and watch the event when the host starts streaming.

A view object must be provided for users to watch the live event when they enter the event. To watch the media content streamed from the host, set the video view by calling liveEvent.setVideoViewForLiveEvent(view:hostId:).

// Provide a video view to show the live event.
liveEvent.enter { error in
   Guard error == nil else { return } // Failed to join a live event.
   }
   // Show the live event video view controller.
}

For a participant to receive the video view of the host who starts the live event, set the video view using liveEvent.host.hostId. When a different user becomes a host during the live event, subscribe to LiveEventListener.didHostEnter(_:host:) and set the video using host.hostId to view the new host’s video.

For the best experience, here are some components included in the SDK that you can use in creating the participant view.

Receive events on a live event

Add LiveEventDelegate so that participants can be notified of actions taken in the live event such as the host entering or exiting the event, muting or unmuting their microphones, stopping or resuming their videos, and the updates of live event states. To see the full list of events, see LiveEventDelegate in the API reference.

Leave a live event

When participants want to leave the live event, they can do so by calling liveEvent.exit().

liveEvent.exit { error in
   guard error == nil else { return }
   // Dismiss the live event video view controller.
}