From 2fd1b98680c0797f56343745c42ab56605e194f1 Mon Sep 17 00:00:00 2001 From: Swapnil Madavi Date: Thu, 25 Apr 2024 13:54:58 +0530 Subject: [PATCH] feat(android-core): add revamped Stage Management section completes: MOB-1632 --- .../stage-management/1-introduction.mdx | 125 ++++++++++++++++++ .../stage-management/2-host-controls.mdx | 91 +++++++++++++ .../3-viewer-participants.mdx | 42 ++++++ .../stage-management/_category_.json | 5 + docs/android-core-new/stage.mdx | 108 --------------- 5 files changed, 263 insertions(+), 108 deletions(-) create mode 100644 docs/android-core-new/stage-management/1-introduction.mdx create mode 100644 docs/android-core-new/stage-management/2-host-controls.mdx create mode 100644 docs/android-core-new/stage-management/3-viewer-participants.mdx create mode 100644 docs/android-core-new/stage-management/_category_.json delete mode 100644 docs/android-core-new/stage.mdx diff --git a/docs/android-core-new/stage-management/1-introduction.mdx b/docs/android-core-new/stage-management/1-introduction.mdx new file mode 100644 index 0000000000..00f9b2f862 --- /dev/null +++ b/docs/android-core-new/stage-management/1-introduction.mdx @@ -0,0 +1,125 @@ +--- +title: Introduction +description: Stage management in Dyte meetings. +sidebar_position: 1 +tags: + - android-core + - stage +--- + +_Below documentation is relevant for Interactive Livestream(LHLS) and Webinar(WebRTC) use cases._ + +Instead of a traditional publish-subscribe model, where a user can publish their media and others can choose to subscribe, Dyte +comes with an optional managed configuration. In this managed configuration, a less privileged user can be configured with a +default behavior to not publish media. The user can then request permission to publish their media, which a privileged user can +choose to grant or deny. + +### Accessing the Stage APIs + +Dyte's stage management APIs allow users to perform actions such as joining and leaving the stage, managing stage requests and +permissions, and kicking participants from the stage. These APIs are accessible through the `meeting.stage` object. + +### Stage Status + +In meetings where stage management is enabled, a user's stage status can change within the values represented by the `DyteStageStatus` +enum. These status values include: + +- `ON_STAGE`: Indicates that the user is currently on the stage and is allowed to publish media. +- `OFF_STAGE`: Indicates that the user is a viewer and is not on the stage. They can see and listen to those on stage. +- `REQUESTED_TO_JOIN_STAGE`: Indicates that the user has a pending request to join the stage. This status is assigned to the user +until the host accepts or rejects their request. +- `ACCEPTED_TO_JOIN_STAGE`: Indicates that the host has accepted the user's request to join the stage. +- `REJECTED_TO_JOIN_STAGE`: Indicates that the host has rejected the user's request to join the stage. The user can request again +to join from this status. + +The `meeting.stage.status` property provides the current stage status of the local user. + +### Viewers + +You can retrieve a list of off-stage participants (viewers) in a stage-enabled meeting by accessing the `meeting.stage.viewers` +property. This property provides a list of `DyteJoinedMeetingParticipant` objects whose stage status is not `ON_STAGE`. + +### Joining the Stage + +To interact with peers and publish media, users can join the stage. This action is only possible if the user's preset allows them +to publish media or if their request to join the stage has been accepted by a host (i.e., their stage status is `ACCEPTED_TO_JOIN_STAGE`). + +```kotlin +meeting.stage.join() +``` + +### Leaving the Stage + +When users want to stop interacting with peers, they can leave the stage. This action stops their media from being published, +and their audio and video are no longer received by others in the room. + +```kotlin +meeting.stage.leave() +``` + +### List of Stage Events + +The `DyteStageEventListener` interface provides callback methods for various stage events. Implement these callbacks to handle +stage-related events in your application: + +```kotlin +meeting.addStageEventsListener(object : DyteStageEventListener { + override fun onPresentRequestReceived() { + // Called when the local user's stage access request is accepted by the host, + // or when the local user, who is a viewer, is invited to the stage by the host. + } + + override fun onAddedToStage() { + // Called when the local user successfully joins the stage. + } + + override fun onRemovedFromStage() { + // Called when the local user is removed from the stage. + } + + override fun onPresentRequestAdded(participant: DyteJoinedMeetingParticipant) { + // Called when a participant requests to join the stage. Triggered only if the local user is a host. + } + + override fun onPresentRequestClosed(participant: DyteJoinedMeetingParticipant) { + // Called when a participant with a pending stage access request leaves the meeting. + // Triggered only if the local user is a host. + } + + override fun onPresentRequestRejected(participant: DyteJoinedMeetingParticipant) { + // Called when a participant's stage access request is denied by the host. + // Triggered only if the local user is a host. + } + + override fun onPresentRequestWithdrawn(participant: DyteJoinedMeetingParticipant) { + // Called when a participant cancels their stage access request. + // Triggered only if the local user is a host. + } + + override fun onParticipantRemovedFromStage(participant: DyteJoinedMeetingParticipant) { + // Called when a participant is removed from the stage by the host. + } + + override fun onStageRequestsUpdated(accessRequests: List) { + // Called when the list of stage access requests is updated. + } + + override fun onParticipantStartedPresenting(participant: DyteJoinedMeetingParticipant) { + // Called when a participant joins the stage. + } + + override fun onParticipantStoppedPresenting(participant: DyteJoinedMeetingParticipant) { + // Called when a participant leaves the stage. + } + + override fun onStageStatusUpdated(stageStatus: DyteStageStatus) { + // Called when the local user's stage status is updated. + } +}) +``` + +Next, we'll explore the Stage Management APIs for hosts, allowing them to manage stage requests, participants in Dyte meetings. + + + Android Core Stage Introduction + \ No newline at end of file diff --git a/docs/android-core-new/stage-management/2-host-controls.mdx b/docs/android-core-new/stage-management/2-host-controls.mdx new file mode 100644 index 0000000000..ee9ebb03ad --- /dev/null +++ b/docs/android-core-new/stage-management/2-host-controls.mdx @@ -0,0 +1,91 @@ +--- +title: Stage Host Controls +description: Stage management APIs for Host in Dyte meetings. +sidebar_position: 2 +tags: + - android-core + - stage +--- + +In a stage management-enabled meeting, a user with the `selfPermissions.host.canAcceptStageRequests` permission as `true` is +considered a host. The `meeting.stage` object in Dyte's Android Core SDK provides stage management APIs that allow hosts to +manage stage access requests, invite participants to the stage, and remove participants from the stage. + +### List of Stage Access Requests + +You can retrieve the list of pending stage access requests by accessing the `meeting.stage.accessRequests` property. This property +provides a list of `DyteJoinedMeetingParticipant` objects who have requested stage access. + +**Note**: If the local user is not a host, this property returns an empty list. + +### Grant Access + +To accept stage access requests or allow a participant directly to the stage, you can use the `grantAccess()` method. +Alternatively, the `grantAccessAll()` method can be used to grant stage access to all participants with pending stage access requests. + +```kotlin +// Grants stage access to a participant +// id: peer id of the stage access requesting participant +meeting.stage.grantAccess(id) + +// Grants stage access to all participants with pending stage access requests +meeting.stage.grantAccessAll() +``` + +### Deny Access + +To reject stage access requests, you can use the `denyAccess()` method. Similarly, the `denyAccessAll()` method can be used to +deny all pending stage access requests. + +```kotlin +// Denies stage access request of a participant +// id: peer id of the stage access requesting participant +meeting.stage.denyAccess(id) + +// Denies all pending stage access requests +meeting.stage.denyAccessAll() +``` + +### Kick Users + +You can remove a participant from the stage by using the `kick()` method. + +```kotlin +// Kicks a participant from stage +// id: peer id of the ON_STAGE participant to kick +meeting.stage.kick(id) +``` + +### Listening to Stage Access Requests + +You can listen to incoming stage access requests or changes in the access requests list if you are a host. The SDK provides the +following callbacks to `DyteStageEventsListener`: + +```kotlin +meeting.addStageEventsListener(object : DyteStageEventsListener { + override fun onPresentRequestAdded(participant: DyteStageParticipant) { + // Called when a user is requesting to join the stage + } + + override fun onPresentRequestClosed(participant: DyteStageParticipant) { + // Called when a user who was trying to join the stage leaves the call + } + + override fun onPresentRequestRejected(participant: DyteStageParticipant) { + // Called when a join stage request is denied by the host + } + + override fun onPresentRequestWithdrawn(participant: DyteStageParticipant) { + // Called when a user who was trying to join the stage withdraws their request to join + } + + override fun onStageRequestsUpdated(accessRequests: List) { + // Called when the access requests list is updated + } +}) +``` + +These APIs enable you to manage stage access requests and participants effectively in Dyte meetings. Next, we'll explore the +Stage APIs available to Viewer participants. + + diff --git a/docs/android-core-new/stage-management/3-viewer-participants.mdx b/docs/android-core-new/stage-management/3-viewer-participants.mdx new file mode 100644 index 0000000000..4e92f5166c --- /dev/null +++ b/docs/android-core-new/stage-management/3-viewer-participants.mdx @@ -0,0 +1,42 @@ +--- +title: Stage Access for Viewers +description: Stage APIs for Viewers in Dyte meetings. +sidebar_position: 3 +tags: + - android-core + - stage +--- + +Viewer participants in a stage-enabled meeting are users whose preset permission for media production is set as `CAN_REQUEST`. +The `meeting.stage` object provides APIs for viewer participants to request stage access and withdraw their join stage request. + +### Request Access + +To request access to the stage, you can call the `requestAccess()` method: + +```kotlin +meeting.stage.requestAccess() +``` + +When a host accepts the user's stage access request or allows the user directly to the stage, the SDK triggers the +`onPresentRequestReceived` callback in `DyteStageEventListener`. You can listen to this event: + +```kotlin +meeting.addStageEventsListener(object : DyteStageEventListener { + override fun onPresentRequestReceived() { + // Host accepted the join stage request or invited user directly to stage + } +}) +``` + +You can then call the `join()` method to finally join the stage. + +**Note**: If the host has directly allowed the user to join the stage and they want to decline, you should use the `leave()` method. + +### Cancel Access Request + +To cancel or withdraw a pending stage access request, you can call the `cancelRequestAccess()` method: + +```kotlin +meeting.stage.cancelRequestAccess() +``` diff --git a/docs/android-core-new/stage-management/_category_.json b/docs/android-core-new/stage-management/_category_.json new file mode 100644 index 0000000000..f47620bf0e --- /dev/null +++ b/docs/android-core-new/stage-management/_category_.json @@ -0,0 +1,5 @@ +{ + "position": 12, + "label": "Stage Management", + "collapsible": true +} diff --git a/docs/android-core-new/stage.mdx b/docs/android-core-new/stage.mdx deleted file mode 100644 index f0031b330a..0000000000 --- a/docs/android-core-new/stage.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Stage Management -sidebar_position: 9 ---- - -_Below documentation relevant for Interactive Livestream(LHLS) and Webinar(WebRTC) use cases_ - -Instead of a traditional publish-subscribe model, where a user can publish their media and others can choose to subscribe, Dyte comes with an optional managed configuration. -In this managed configuration, a less privileged can be configured with a default behavior to not publish media and the user can then request for permission to be allowed to publish their media, where then a privileged user can choose to grant or deny access. - -Using Dyte's stage management APIs a user can do actions such as leave and join stage, manage stage requests and permissions, kick participants and so on. - -## Access the stage APIs - -The stage module can be accessed under [`meeting.stage`](/react-web-core/reference/DyteStage) namespace. - -## Properties - -### Status - -`meeting.stage.status` returns the current stage status of the local user - -- **ON_STAGE**: This value indicates that the user is currently on the stage and participating in the live stream. -- **OFF_STAGE**: This value means that the user is viewing the live stream but is not on the stage. -- **REQUESTED_TO_JOIN_STAGE**: The user has a pending request to join livestream. If the user has made a request to join the stage, this value will be assigned to their status until the host accepts or rejects their request. -- **ACCEPTED_TO_JOIN_STAGE**: The host has accepted user's request to join livestream. If the host accepts the user's request to join the stage, this value will be assigned to the user's status. - -A user with permission to join stage directly can only assume `ON_STAGE` and `ACCEPTED_TO_JOIN_STAGE` status values. - -## Host controls - -Dyte's stage management APIs allow hosts to receive and manage stage requests as well as leave and join the stage. - -### Join stage - -This method connects the user to the media room, enabling them to interact with other peers in the meeting. - -`await meeting.stage.join();` - -### Leave stage - -By employing this method, the user will be disconnected from the media room and subsequently unable to communicate with their peers. Additionally, their audio and video will no longer be visible to others in the room. - -`await meeting.stage.leave();` - -### Grant access - -A privileged user can grant access to stage for a set of users with `grantAccess` method. - -| **Parameters** | **Type** | -| -------------- | -------- | -| userIds | string[] | - -`await meeting.stage.grantAccess(userIds);` - -### Deny access - -A privileged user can deny access to stage for a set of users with `denyAccess` method. - -| **Parameters** | **Type** | -| -------------- | -------- | -| userIds | string[] | - -`await meeting.stage.denyAccess(userIds);` - -### Kick users - -A privileged user can remove a set of users from stage using the `kick` method - -| **Parameters** | **Type** | -| -------------- | -------- | -| userIds | string[] | - -`await meeting.stage.kick(userIds);` - -## Participant controls - -Dyte's stage management APIs allow participants to receive and manage stage requests as well as leave and join the stage. - -### Request access - -This method is used to create a new stage request which can be approved by the host. Each user (viewer or host) must call this method in order to join the stage. - -When the host calls this method, their status will be updated to `ACCEPTED_TO_JOIN_STAGE`. - -`await meeting.stage.requestAccess();` - -### Cancel access request - -You can call this method in order to cancel your stage request. - -`await meeting.stage.cancelRequestAccess();` - -## Events - -Here is a list of events that the `meeting.stage` module emits: - -| **Event** | **Description** | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `stageAccessRequestUpdate` | Emitted to the users with the permission `acceptPresentRequests` set to true. When a new request is made or a request is cancelled, this event is triggered. It contains the updated list of stage requests in its payload. | -| `stageStatusUpdate` | Emitted when the user's stage status changes. It contains the updated stage status in the payload. | -| `newStageRequest` | Emitted to the users with the permission `acceptPresentRequests` set to true. This event is triggered when there are new stage requests. It contains the number of stage requests in its payload. For example, to show notifications. | -| `stageRequestApproved` | Emitted when a user's request to join stage has been approved. | -| `stageRequestRejected` | Emitted when a user's request to join stage has been rejected. | - - - Web Core Stage Management -