feat(android-core): add revamped Stage Management section

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<DyteJoinedMeetingParticipant>) {
+ // 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.
+
+<head>
+ <title>Android Core Stage Introduction</title>
+</head>

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<DyteJoinedMeetingParticipant>) {
+ // 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.
+
+

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()
+```

docs/android-core-new/stage-management/_category_.json

@@ -0,0 +1,5 @@
+{
+ "position": 12,
+ "label": "Stage Management",
+ "collapsible": true
+}