|
| 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 | +> [!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 'beta' 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 | +```swift |
| 16 | +import AzureCommunicationCalling |
| 17 | +``` |
| 18 | + |
| 19 | +Then you can get the feature API object from the call instance: |
| 20 | + |
| 21 | +```swift |
| 22 | +@State var raisehandFeature: RaiseHandCallFeature? |
| 23 | + |
| 24 | +raiseHandFeature = self.call!.feature(Features.raiseHand) |
| 25 | +``` |
| 26 | + |
| 27 | +### Raise and lower hand for current participant: |
| 28 | +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. |
| 29 | +If it Teams meeting - organizer will have ability to enable or disable raise hand states for all participants. |
| 30 | +To change state for current participant, you can use methods: |
| 31 | +```swift |
| 32 | +//publish raise hand state for local participant |
| 33 | +raisehandFeature.raiseHand(completionHandler: { (error) in |
| 34 | + if let error = error { |
| 35 | + print ("Feature failed raise a hand %@", error as Error) |
| 36 | + } |
| 37 | +}) |
| 38 | + |
| 39 | +//remove raise hand state for local participant |
| 40 | +raisehandFeature.lowerHand(completionHandler: { (error) in |
| 41 | + if let error = error { |
| 42 | + print ("Feature failed lower hand %@", error as Error) |
| 43 | + } |
| 44 | +}) |
| 45 | + |
| 46 | +``` |
| 47 | + |
| 48 | +### Lower hands for other participants |
| 49 | +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: |
| 50 | +```swift |
| 51 | + |
| 52 | +// remove raise hand states for all participants on the call |
| 53 | +raisehandFeature.lowerHandForEveryone(completionHandler: { (error) in |
| 54 | + if let error = error { |
| 55 | + print ("Feature failed lower all hands %@", error as Error) |
| 56 | + } |
| 57 | +}) |
| 58 | + |
| 59 | +// remove raise hand states for all remote participants on the call |
| 60 | +let identifiers = (call?.remoteParticipants.map {$0.identifier})!; |
| 61 | +raisehandFeature.lowerHand(participants: identifiers, completionHandler: { (error) in |
| 62 | + if let error = error { |
| 63 | + print ("Feature failed lower hands %@", error as Error) |
| 64 | + } |
| 65 | +}) |
| 66 | + |
| 67 | +// remove raise hand state of specific user |
| 68 | +var identifiers : [CommunicationIdentifier] = [] |
| 69 | +identifiers.append(CommunicationUserIdentifier("<USER_ID>")) |
| 70 | +raisehandFeature.lowerHand(participants: identifiers, completionHandler: { (error) in |
| 71 | + if let error = error { |
| 72 | + print ("Feature failed lower hands %@", error as Error) |
| 73 | + } |
| 74 | +}) |
| 75 | + |
| 76 | +``` |
| 77 | + |
| 78 | +### Handle changed states |
| 79 | +The `Raise Hand` API allows you to subscribe to `didReceiveRaiseHandEvent` events. A `didReceiveRaiseHandEvent` event comes from a `call` instance and contain information about participant and new state. |
| 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, isRaised: true, order:1} |
| 89 | + public func raiseHandCallFeature(_ raiseHandCallFeature: RaiseHandCallFeature, didReceiveRaiseHandEvent args: RaiseHandEvent) { |
| 90 | + os_log("Raise hand feature updated: %s : %d", log:log, Utilities.toMri(args.identifier), args.isRaised) |
| 91 | + raiseHandCallFeature.status.forEach { raiseHand in |
| 92 | + os_log("Raise hand active: %s", log:log, Utilities.toMri(raiseHand.identifier)) |
| 93 | + } |
| 94 | + } |
| 95 | +} |
| 96 | +``` |
| 97 | + |
| 98 | +### List of all participants with active state |
| 99 | +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: |
| 100 | +```swift |
| 101 | +raisehandFeature = self.call!.feature(Features.raiseHand) |
| 102 | +raisehandFeature.status.forEach { raiseHand in |
| 103 | + os_log("Raise hand active: %s", log:log, Utilities.toMri(raiseHand.identifier)) |
| 104 | +} |
| 105 | +``` |
| 106 | + |
| 107 | +### Order of raised Hands |
| 108 | +It possible to get order of all raised hand states on the call, order is started from 1 and will be sorted. |
| 109 | +There are two ways: get all raise hand state on the call or use `didReceiveRaiseHandEvent` event subscription. |
| 110 | +In event subscription when any participant will lower a hand - call will generate only one event, but not for all participants with order above. |
| 111 | + |
| 112 | +```swift |
| 113 | +raisehandFeature = self.call!.feature(Features.raiseHand) |
| 114 | +raisehandFeature.status.forEach { raiseHand in |
| 115 | + os_log("Raise hand active: %s with order %d", log:log, Utilities.toMri(raiseHand.identifier), raiseHand.order) |
| 116 | +} |
| 117 | +``` |
0 commit comments