|
| 1 | +--- |
| 2 | +author: ruslanzdor |
| 3 | +ms.service: azure-communication-services |
| 4 | +ms.topic: include |
| 5 | +ms.date: 11/01/2022 |
| 6 | +ms.author: ruslanzdor |
| 7 | +--- |
| 8 | +[!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)] |
| 9 | + |
| 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: |
| 14 | + |
| 15 | +```js |
| 16 | +import com.azure.android.communication.calling.RaiseHandFeature; |
| 17 | +``` |
| 18 | + |
| 19 | +Then you can get the feature API object from the call instance: |
| 20 | + |
| 21 | +```js |
| 22 | +RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND); |
| 23 | +``` |
| 24 | + |
| 25 | +### 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 |
| 30 | +RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND); |
| 31 | +//raise |
| 32 | +raiseHandFeature.raiseHand(); |
| 33 | +//lower |
| 34 | +raiseHandFeature.lowerHand(); |
| 35 | +``` |
| 36 | + |
| 37 | +### 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 |
| 40 | +RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND); |
| 41 | +//lower all hands on the call |
| 42 | +raiseHandFeature.lowerHandForEveryone(); |
| 43 | +//or we can provide array of CommunicationIdentifier to specify list of participants |
| 44 | +List<CommunicationIdentifier> identifiers = new ArrayList<>(); |
| 45 | +CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>); |
| 46 | +MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>); |
| 47 | +identifiers.add(new CommunicationUserIdentifier("<USER_ID>")); |
| 48 | +identifiers.add(new MicrosoftTeamsUserIdentifier("<USER_ID>")); |
| 49 | +raiseHandFeature.lowerHand(identifiers); |
| 50 | +``` |
| 51 | + |
| 52 | +### 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 |
| 55 | +RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND) |
| 56 | + |
| 57 | +// event example : {identifier: CommunicationIdentifier, isRaised: true, order:1} |
| 58 | +call.feature(Features.RAISE_HAND).addOnRaiseHandReceivedListener(raiseHandEvent -> { |
| 59 | + Log.i(TAG, String.format("Raise Hand: %s : %s", Utilities.toMRI(raiseHandEvent.getIdentifier()), raiseHandEvent.isRaised())); |
| 60 | +}); |
| 61 | +``` |
| 62 | + |
| 63 | +### 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 |
| 66 | +RaiseHandFeature raiseHandFeature = call.feature(Features.RAISE_HAND); |
| 67 | +List<RaiseHand> activeStates = raiseHandFeature.getStatus(); |
| 68 | +``` |
| 69 | + |
| 70 | +### 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 | +``` |
0 commit comments