Skip to content

Commit ddc429a

Browse files
v-regandownerv-regandowner
authored
Merge pull request #229653 from rzdor/main
Add raise hand feature doc for iOS and Windows
2 parents d1241d0 + 572644a commit ddc429a

File tree

6 files changed

+294
-72
lines changed

6 files changed

+294
-72
lines changed

‎articles/communication-services/how-tos/calling-sdk/includes/raise-hand/raise-hand-android.md

Lines changed: 30 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,23 @@ ms.author: ruslanzdor
77
---
88
[!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)]
99

10-
> [!NOTE]
11-
> Raise Hand API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. To use this api please use 'alpha' release of Azure Communication Services Calling Web SDK
10+
The Raise Hand feature allows participants in a call to indicate that they have a question, comment, or concern without interrupting the speaker or other participants. This feature can be used in any call type, including 1:1 calls and calls with many participants, in Azure Communication Service and in Teams calls.
11+
You first need to import calling Features from the Calling SDK:
1212

13-
Raise Hand is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK:
14-
15-
```js
13+
```java
1614
import com.azure.android.communication.calling.RaiseHandFeature;
1715
```
1816

1917
Then you can get the feature API object from the call instance:
2018

21-
```js
19+
```java
2220
RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND);
2321
```
2422

2523
### Raise and lower hand for current participant:
26-
Raise Hand state can be used in any call type: on 1:1 calls and on calls with many participants, in ACS and in Teams calls.
27-
If it Teams meeting - organizer will have ability to enable or disable raise hand states for all participants.
28-
To change state for current participant, you can use methods:
29-
```js
24+
To change the Raise Hand state for the current participant, you can use the `raiseHand()` and `lowerHand()` methods.
25+
This is async methods, to verify results can be used `RaisedHandReceived` and `LoweredHandReceived` listeners.
26+
```java
3027
RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND);
3128
//raise
3229
raiseHandFeature.raiseHand();
@@ -35,53 +32,49 @@ raiseHandFeature.lowerHand();
3532
```
3633

3734
### Lower hands for other participants
38-
Currently ACS calls aren't allowed to change state of other participants, for example, lower all hands. But Teams calls allow it using these methods:
39-
```js
35+
This feature allows users with the Organizer and Presenter roles to lower all hands for other participants on Teams calls. In Azure Communication calls, changing the state of other participants is not allowed unless roles have been added.
36+
37+
To use this feature, you can use the following code:
38+
```java
4039
RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND);
4140
//lower all hands on the call
42-
raiseHandFeature.lowerHandForEveryone();
41+
raiseHandFeature.lowerAllHands();
4342
//or we can provide array of CommunicationIdentifier to specify list of participants
4443
List<CommunicationIdentifier> identifiers = new ArrayList<>();
4544
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
4645
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
4746
identifiers.add(new CommunicationUserIdentifier("<USER_ID>"));
4847
identifiers.add(new MicrosoftTeamsUserIdentifier("<USER_ID>"));
49-
raiseHandFeature.lowerHand(identifiers);
48+
raiseHandFeature.lowerHands(identifiers);
5049
```
5150

5251
### Handle changed states
53-
The `Raise Hand` API allows you to subscribe to `raiseHandChanged` events. A `raiseHandChanged` event comes from a `call` instance and contain information about participant and new state.
54-
```js
52+
With the Raise Hand API, you can subscribe to the `RaisedHandReceived` and `LoweredHandReceived` events to handle changes in the state of participants on a call. These events are triggered by a call instance and provide information about the participant whose state has changed.
53+
54+
To subscribe to these events, you can use the following code:
55+
```java
5556
RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND)
5657

5758
// event example : {identifier: CommunicationIdentifier, isRaised: true, order:1}
58-
call.feature(Features.RAISE_HAND).addOnRaiseHandReceivedListener(raiseHandEvent -> {
59+
call.feature(Features.RAISE_HAND).addOnRaisedHandReceivedListener(raiseHandEvent -> {
5960
Log.i(TAG, String.format("Raise Hand: %s : %s", Utilities.toMRI(raiseHandEvent.getIdentifier()), raiseHandEvent.isRaised()));
6061
});
6162
```
63+
The `RaisedHandReceived` and `LoweredHandReceived` events contain an object with the `identifier` property, which represents the participant's communication identifier. In the example above, we log a message to the console indicating that a participant has raised their hand.
64+
65+
To unsubscribe from the events, you can use the `off` method.
66+
6267

6368
### List of all participants with active state
64-
To get information about all participants that have Raise Hand state on current call, you can use this api array is sorted by order field:
65-
```js
69+
To get information about all participants that have raised hand state on current call, you can use the `getRaisedHands` api. he returned array is sorted by the order field.
70+
Here's an example of how to use the `getRaisedHands` API:
71+
```java
6672
RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND);
67-
List<RaiseHand> activeStates = raiseHandFeature.getStatus();
73+
List<RaiseHand> participantsWithRaisedHands = raiseHandFeature.getRaisedHands();
6874
```
6975

7076
### Order of raised Hands
71-
It possible to get order of all raised hand states on the call, this order is started from 1.
72-
There are two ways: get all raise hand state on the call or use `raiseHandChanged` event subscription.
73-
In event subscription when any participant will lower a hand - call will generate only one event, but not for all participants with order above.
74-
75-
```js
76-
const raiseHandFeature = call.feature(Features.RaiseHand );
77-
for (RaiseHand state : raiseHandFeature.getStatus() {
78-
CommunicationIdentifier identifier = state.getIdentifier();
79-
int order = state.getOrder();
80-
}
81-
82-
83-
// event example: {identifier: CommunicationIdentifier, isRaised: true, order:1}
84-
call.feature(Features.RAISE_HAND).addOnRaiseHandReceivedListener(raiseHandEvent -> {
85-
Log.i(TAG, String.format("Raise Hand: %s : %s", Utilities.toMRI(raiseHandEvent.getIdentifier()), raiseHandEvent.getOrder()));
86-
});
87-
```
77+
The `participantsWithRaisedHands` variable will contain an array of participant objects, where each object has the following properties:
78+
`identifier`: the communication identifier of the participant
79+
`order`: the order in which the participant raised their hand
80+
You can use this information to display a list of participants with the Raise Hand state and their order in the queue.```

‎articles/communication-services/how-tos/calling-sdk/includes/raise-hand/raise-hand-ios.md

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
author: ruslanzdor
3+
ms.service: azure-communication-services
4+
ms.topic: include
5+
ms.date: 02/06/2022
6+
ms.author: ruslanzdor
7+
---
8+
[!INCLUDE [Install SDK](../install-sdk/install-sdk-ios.md)]
9+
10+
The Raise Hand feature allows participants in a call to indicate that they have a question, comment, or concern without interrupting the speaker or other participants. This feature can be used in any call type, including 1:1 calls and calls with many participants, in Azure Communication Service and in Teams calls.
11+
You first need to import calling Features from the Calling SDK:
12+
13+
```swift
14+
import AzureCommunicationCalling
15+
```
16+
17+
Then you can get the feature API object from the call instance:
18+
19+
```swift
20+
@State var raisehandFeature: RaiseHandCallFeature?
21+
22+
raiseHandFeature = self.call!.feature(Features.raiseHand)
23+
```
24+
25+
### Raise and lower hand for current participant:
26+
To change the Raise Hand state for the current participant, you can use the `raiseHand()` and `lowerHand()` methods.
27+
```swift
28+
//publish raise hand state for local participant
29+
raisehandFeature.raiseHand(completionHandler: { (error) in
30+
if let error = error {
31+
print ("Feature failed raise a hand %@", error as Error)
32+
}
33+
})
34+
35+
//remove raise hand state for local participant
36+
raisehandFeature.lowerHand(completionHandler: { (error) in
37+
if let error = error {
38+
print ("Feature failed lower hand %@", error as Error)
39+
}
40+
})
41+
42+
```
43+
44+
### Lower hands for other participants
45+
This feature allows users with the Organizer and Presenter roles to lower all hands for other participants on Teams calls. In Azure Communication calls, changing the state of other participants is not allowed unless roles have been added.
46+
47+
To use this feature, you can use the following code:
48+
```swift
49+
50+
// remove raise hand states for all participants on the call
51+
raisehandFeature.lowerAllHands(completionHandler: { (error) in
52+
if let error = error {
53+
print ("Feature failed lower all hands %@", error as Error)
54+
}
55+
})
56+
57+
// remove raise hand states for all remote participants on the call
58+
let identifiers = (call?.remoteParticipants.map {$0.identifier})!;
59+
raisehandFeature.lowerHands(participants: identifiers, completionHandler: { (error) in
60+
if let error = error {
61+
print ("Feature failed lower hands %@", error as Error)
62+
}
63+
})
64+
65+
// remove raise hand state of specific user
66+
var identifiers : [CommunicationIdentifier] = []
67+
identifiers.append(CommunicationUserIdentifier("<USER_ID>"))
68+
raisehandFeature.lowerHands(participants: identifiers, completionHandler: { (error) in
69+
if let error = error {
70+
print ("Feature failed lower hands %@", error as Error)
71+
}
72+
})
73+
74+
```
75+
76+
### Handle changed states
77+
With the Raise Hand API, you can subscribe to the `RaisedHandReceived` and `LoweredHandReceived` events to handle changes in the state of participants on a call. These events are triggered by a call instance and provide information about the participant whose state has changed.
78+
79+
To subscribe to these events, you can use the following code:
80+
```swift
81+
self.callObserver = CallObserver(view:self)
82+
83+
raisehandFeature = self.call!.feature(Features.raiseHand)
84+
raisehandFeature!.delegate = self.callObserver
85+
86+
public class CallObserver : NSObject, RaiseHandCallFeatureDelegate
87+
{
88+
// event example : {identifier: CommunicationIdentifier}
89+
public func raiseHandCallFeature(_ raiseHandCallFeature: RaiseHandCallFeature, didReceiveRaisedHand args: RaisedHandChangedEventArgs) {
90+
os_log("Raise hand feature updated: %s is raised hand", log:log, Utilities.toMri(args.identifier))
91+
raiseHandCallFeature.raisedHands.forEach { raiseHand in
92+
os_log("Raise hand active: %s", log:log, Utilities.toMri(raiseHand.identifier))
93+
}
94+
}
95+
public func raiseHandCallFeature(_ raiseHandCallFeature: RaiseHandCallFeature, didReceiveLoweredHand args: LoweredHandChangedEventArgs) {
96+
os_log("Raise hand feature updated: %s is lowered hand", log:log, Utilities.toMri(args.identifier))
97+
raiseHandCallFeature.raisedHands.forEach { raiseHand in
98+
os_log("Raise hand active: %s", log:log, Utilities.toMri(raiseHand.identifier))
99+
}
100+
}
101+
}
102+
```
103+
The `RaisedHandReceived` and `LoweredHandReceived` events contain an object with the `identifier` property, which represents the participant's communication identifier. In the example above, we log a message to the console indicating that a participant has raised their hand.
104+
105+
To unsubscribe from the events, you can use the `off` method.
106+
107+
108+
### List of all participants with active state
109+
To get information about all participants that have raised hand state on current call, you can use the `getRaisedHands` api. he returned array is sorted by the order field.
110+
Here's an example of how to use the `raisedHands` API:
111+
```swift
112+
raisehandFeature = self.call!.feature(Features.raiseHand)
113+
raisehandFeature.raisedHands.forEach { raiseHand in
114+
os_log("Raise hand active: %s", log:log, Utilities.toMri(raiseHand.identifier))
115+
}
116+
```
117+
118+
### Order of raised Hands
119+
The `raisedHands` variable will contain an array of participant objects, where each object has the following properties:
120+
`identifier`: the communication identifier of the participant
121+
`order`: the order in which the participant raised their hand
122+
You can use this information to display a list of participants with the Raise Hand state and their order in the queue.```

‎articles/communication-services/how-tos/calling-sdk/includes/raise-hand/raise-hand-web.md

Lines changed: 30 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,8 @@ ms.author: rifox
77
---
88
[!INCLUDE [Install SDK](../install-sdk/install-sdk-web.md)]
99

10-
> [!NOTE]
11-
> Raise Hand API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. To use this api please use 'alpha' release of Azure Communication Services Calling Web SDK
12-
13-
Raise Hand is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK:
10+
The Raise Hand feature allows participants in a call to indicate that they have a question, comment, or concern without interrupting the speaker or other participants. This feature can be used in any call type, including 1:1 calls and calls with many participants, in Azure Communication Service and in Teams calls.
11+
You first need to import calling Features from the Calling SDK:
1412

1513
```js
1614
import { Features} from "@azure/communication-calling";
@@ -23,9 +21,8 @@ const raiseHandFeature = call.feature(Features.RaiseHand );
2321
```
2422

2523
### Raise and lower hand for current participant:
26-
Raise Hand state can be used in any call type: on 1:1 calls and on calls with many participants, in ACS and in Teams calls.
27-
If it Teams meeting - organizer will have ability to enable or disable raise hand states for all participants.
28-
To change state for current participant, you can use methods:
24+
To change the Raise Hand state for the current participant, you can use the `raiseHand()` and `lowerHand()` methods.
25+
This is async methods, to verify results can be used `raisedHandChanged` and `loweredHandChanged` listeners.
2926
```js
3027
const raiseHandFeature = call.feature(Features.RaiseHand );
3128
//raise
@@ -35,51 +32,51 @@ raiseHandFeature.lowerHand();
3532
```
3633

3734
### Lower hands for other participants
38-
Currently ACS calls aren't allowed to change state of other participants, for example, lower all hands. But Teams calls allow it using these methods:
35+
This feature allows users with the Organizer and Presenter roles to lower all hands for other participants on Teams calls. In Azure Communication calls, changing the state of other participants is not allowed unless roles have been added.
36+
37+
To use this feature, you can use the following code:
3938
```js
4039
const raiseHandFeature = call.feature(Features.RaiseHand );
4140
//lower all hands on the call
42-
raiseHandFeature.lowerHandForEveryone();
41+
raiseHandFeature.lowerAllHands();
4342
//or we can provide array of CommunicationIdentifier to specify list of participants
4443
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
4544
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>)
4645
CommunicationIdentifier participants[] = new CommunicationIdentifier[]{ acsUser, teamsUser };
47-
raiseHandFeature.lowerHand(participants);
46+
raiseHandFeature.lowerHands(participants);
4847
```
4948

5049
### Handle changed states
51-
The `Raise Hand` API allows you to subscribe to `raiseHandChanged` events. A `raiseHandChanged` event comes from a `call` instance and contain information about participant and new state.
50+
With the Raise Hand API, you can subscribe to the `raisedHandChanged` and `loweredHandChanged` events to handle changes in the state of participants on a call. These events are triggered by a call instance and provide information about the participant whose state has changed.
51+
52+
To subscribe to these events, you can use the following code:
5253
```js
5354
const raiseHandFeature = call.feature(Features.RaiseHand );
5455

55-
// event : {identifier: CommunicationIdentifier, isRaised: true, order:1}
56-
const isRaiseHandChangedHandler = (event) => {
57-
console.log(`Participant ${event.identifier} ${event.isRaised ? "Raised" : "Lower"} hand`);
56+
// event : {identifier: CommunicationIdentifier}
57+
const raisedHandChangedHandler = (event) => {
58+
console.log(`Participant ${event.identifier} raised hand`);
5859
};
59-
raiseHandFeature.feature(SDK.Features.RaiseHand).on('raiseHandChanged', isRaiseHandChangedHandler):
60+
const loweredHandChangedHandler = (event) => {
61+
console.log(`Participant ${event.identifier} lowered hand`);
62+
};
63+
raiseHandFeature.on('raisedHandChanged', raisedHandChangedHandler):
64+
raiseHandFeature.on('loweredHandChanged', loweredHandChangedHandler):
6065
```
66+
The `raisedHandChanged` and `loweredHandChanged` events contain an object with the `identifier` property, which represents the participant's communication identifier. In the example above, we log a message to the console indicating that a participant has raised their hand.
67+
68+
To unsubscribe from the events, you can use the `off` method.
6169

6270
### List of all participants with active state
63-
To get information about all participants that have Raise Hand state on current call, you can use this api array is sorted by order field:
71+
To get information about all participants that have raised hand state on current call, you can use the `getRaisedHands` api. he returned array is sorted by the order field.
72+
Here's an example of how to use the `getRaisedHands` API:
6473
```js
6574
const raiseHandFeature = call.feature(Features.RaiseHand );
66-
let activeStates = raiseHandFeature.getStatus();
75+
let participantsWithRaisedHands = raiseHandFeature.getRaisedHands();
6776
```
6877

6978
### Order of raised Hands
70-
It possible to get order of all raised hand states on the call, this order is started from 1.
71-
There are two ways: get all raise hand state on the call or use `raiseHandChanged` event subscription.
72-
In event subscription when any participant will lower a hand - call will generate only one event, but not for all participants with order above.
73-
74-
```js
75-
const raiseHandFeature = call.feature(Features.RaiseHand );
76-
77-
// event : {identifier: CommunicationIdentifier, isRaised: true, order:1}
78-
const isRaiseHandChangedHandler = (event) => {
79-
console.log(`List of participants with raised hand`);
80-
for (let state : raiseHandFeature.getStatus()) {
81-
console.log(`Participant ${state.identifier} has order ${state.order}`);
82-
}
83-
};
84-
raiseHandFeature.feature(SDK.Features.RaiseHand).on('raiseHandChanged', isRaiseHandChangedHandler):
85-
```
79+
The `participantsWithRaisedHands` variable will contain an array of participant objects, where each object has the following properties:
80+
`identifier`: the communication identifier of the participant
81+
`order`: the order in which the participant raised their hand
82+
You can use this information to display a list of participants with the Raise Hand state and their order in the queue.

0 commit comments

Comments
 (0)