Skip to content

Commit 327bb17

Browse files
Stacyrch140Stacyrch140
authored
Merge pull request #247447 from cn0151/cnwankwo/spotlight_native_docs
Cnwankwo/spotlight native docs
2 parents 5b923c7 + ff25ab7 commit 327bb17

File tree

5 files changed

+411
-22
lines changed

5 files changed

+411
-22
lines changed

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

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
---
2+
author: cnwankwo
3+
ms.service: azure-communication-services
4+
ms.topic: include
5+
ms.date: 06/20/2023
6+
ms.author: cnwankwo
7+
---
8+
[!INCLUDE [Install SDK](../install-sdk/install-sdk-android.md)]
9+
10+
Communication Services or Microsoft 365 users can call the spotlight APIs based on role type and conversation type
11+
12+
**In a one to one call or group call scenario, the following APIs are supported for both Communication Services and Microsoft 365 users**
13+
14+
|APIs| Organizer | Presenter | Attendee |
15+
|----------------------------------------------|--------|--------|--------|
16+
| startSpotlight | ✔️ | ✔️ | ✔️ |
17+
| stopSpotlight | ✔️ | ✔️ | ✔️ |
18+
| stopAllSpotlight | ✔️ | ✔️ | ✔️ |
19+
| getSpotlightedParticipants | ✔️ | ✔️ | ✔️ |
20+
| maxSupported | ✔️ | ✔️ | ✔️ |
21+
22+
**For meeting scenario the following APIs are supported for both Communication Services and Microsoft 365 users**
23+
24+
|APIs| Organizer | Presenter | Attendee |
25+
|----------------------------------------------|--------|--------|--------|
26+
| startSpotlight | ✔️ | ✔️ | |
27+
| stopSpotlight | ✔️ | ✔️ | ✔️ |
28+
| stopAllSpotlight | ✔️ | ✔️ | |
29+
| getSpotlightedParticipants | ✔️ | ✔️ | ✔️ |
30+
| maxSupported | ✔️ | ✔️ | ✔️ |
31+
32+
Spotlight is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK:
33+
34+
```java
35+
import com.azure.android.communication.calling.SpotlightFeature;
36+
```
37+
38+
Then you can get the feature API object from the call instance:
39+
40+
```java
41+
SpotlightCallFeature spotlightCallFeature;
42+
spotlightCallFeature = call.feature(Features.SPOTLIGHT);
43+
```
44+
### Start spotlight for participants:
45+
Any participant in the call or meeting can be pinned. Only Microsoft 365 users who have an organizer, co-organizer or presenter role can start spotlight for other participants. This action is idempotent, trying to start spotlight on a pinned participant does nothing
46+
47+
To use this feature, a list of participants identifiers is required
48+
```java
49+
List<CommunicationIdentifier> spotlightIdentifiers = new ArrayList<>();
50+
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
51+
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
52+
spotlightIdentifiers.add(new CommunicationUserIdentifier("<USER_ID>"));
53+
spotlightIdentifiers.add(new MicrosoftTeamsUserIdentifier("<USER_ID>"));
54+
spotlightCallFeature.StartSpotlight(spotlightIdentifiers);
55+
```
56+
The following API can also be used to start the spotlight of participants
57+
```java
58+
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
59+
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
60+
spotlightCallFeature.StartSpotlight(acsUser, teamsUser);
61+
```
62+
63+
### Remove spotlight from participants
64+
Any pinned participant in the call or meeting can be unpinned. Only Microsoft 365 users who have an organizer, co-organizer or presenter role can unpin other participants. This action is idempotent, trying to stop spotlight on an unpinned participant does nothing
65+
66+
To use this feature, a list of participants identifiers is required
67+
```java
68+
List<CommunicationIdentifier> spotlightIdentifiers = new ArrayList<>();
69+
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
70+
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
71+
spotlightIdentifiers.add(new CommunicationUserIdentifier("<USER_ID>"));
72+
spotlightIdentifiers.add(new MicrosoftTeamsUserIdentifier("<USER_ID>"));
73+
spotlightCallFeature.StopSpotlight(spotlightIdentifiers);
74+
```
75+
The following API can also be used to remove the spotlight of participants
76+
```java
77+
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
78+
MicrosoftTeamsUserIdentifier teamsUser = new MicrosoftTeamsUserIdentifier(<USER_ID>);
79+
spotlightCallFeature.StopSpotlight(acsUser, teamsUser);
80+
```
81+
### Remove all spotlights
82+
All pinned participants can be unpinned using this API. Only MicrosoftTeamsUserIdentifier users who have an organizer, co-organizer or presenter role can unpin all participants.
83+
```java
84+
spotlightCallFeature.stopAllSpotlight();
85+
```
86+
87+
### Handle changed states
88+
The `Spotlight` API allows you to subscribe to `SpotlightChanged` events. A `SpotlightChanged` event comes from a `call` instance and contains information about newly spotlighted participants and participants whose spotlight were stopped
89+
```java
90+
import com.azure.android.communication.calling.SpotlightedParticipant;
91+
92+
// event : { added: SpotlightedParticipant[]; removed: SpotlightedParticipant[] }
93+
// SpotlightedParticipant = { identifier: CommunicationIdentifier }
94+
// where:
95+
// identifier: ID of participant whos spotlight state is changed
96+
void onSpotlightChanged(SpotlightChangedEvent args) {
97+
Log.i(ACTIVITY_TAG, String.format("Spotlight Changed Event"));
98+
for(SpotlightedParticipant participant: args.getadded()) {
99+
Log.i(ACTIVITY_TAG, String.format("Added ==>: %s %d", Utilities.toMRI(participant.getIdentifier())));
100+
}
101+
102+
for(SpotlightedParticipant participant: args.getremoved()) {
103+
Log.i(ACTIVITY_TAG, String.format("Removed ==>: %s %d", Utilities.toMRI(participant.getIdentifier())));
104+
}
105+
}
106+
spotlightCallFeature.addOnSpotlightChangedListener(onSpotlightChanged);
107+
```
108+
109+
### Get all spotlighted participants:
110+
To get information about all participants that have spotlight state on current call, you can use the following API. The returned array is sorted by the order the participants were spotlighted.
111+
112+
``` java
113+
List<SpotlightedParticipant> currentSpotlightedParticipants = spotlightCallFeature.getSpotlightedParticipants();
114+
foreach (SpotlightedParticipant participant in currentSpotlightedParticipants)
115+
{
116+
Trace.WriteLine("Participant " + participant.Identifier.RawId + " has spotlight");
117+
}
118+
```
119+
120+
### Get the maximum supported spotlight:
121+
The following API can be used to get the maximum number of participants that can be spotlighted using the Calling SDK
122+
``` java
123+
spotlightCallFeature.maxSupported();
124+
```

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
author: cnwankwo
3+
ms.service: azure-communication-services
4+
ms.topic: include
5+
ms.date: 08/06/2023
6+
ms.author: cnwankwo
7+
---
8+
[!INCLUDE [Install SDK](../install-sdk/install-sdk-ios.md)]
9+
10+
Communication Services or Microsoft 365 users can call the spotlight APIs based on role type and conversation type
11+
12+
**In a one to one call or group call scenario, the following APIs are supported for both Communication Services and Microsoft 365 users**
13+
14+
|APIs| Organizer | Presenter | Attendee |
15+
|----------------------------------------------|--------|--------|--------|
16+
| startSpotlight | ✔️ | ✔️ | ✔️ |
17+
| stopSpotlight | ✔️ | ✔️ | ✔️ |
18+
| stopAllSpotlight | ✔️ | ✔️ | ✔️ |
19+
| spotlightedParticipants | ✔️ | ✔️ | ✔️ |
20+
| maxSupported | ✔️ | ✔️ | ✔️ |
21+
22+
**For meeting scenario the following APIs are supported for both Communication Services and Microsoft 365 users**
23+
24+
|APIs| Organizer | Presenter | Attendee |
25+
|----------------------------------------------|--------|--------|--------|
26+
| startSpotlight | ✔️ | ✔️ | |
27+
| stopSpotlight | ✔️ | ✔️ | ✔️ |
28+
| stopAllSpotlight | ✔️ | ✔️ | |
29+
| spotlightedParticipants | ✔️ | ✔️ | ✔️ |
30+
| maxSupported | ✔️ | ✔️ | ✔️ |
31+
32+
Spotlight is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK:
33+
34+
```swift
35+
import AzureCommunicationCalling
36+
```
37+
38+
Then you can get the feature API object from the call instance:
39+
40+
```swift
41+
@State var spotlightFeature: SpotlightCallFeature?
42+
43+
spotlightFeature = self.call!.feature(Features.spotlight)
44+
```
45+
46+
### Start spotlight for participants:
47+
Any participant in the call or meeting can be pinned. Only Microsoft 365 users who have an organizer, co-organizer or presenter role can start spotlight for other participants. This action is idempotent, trying to start spotlight on a pinned participant does nothing
48+
49+
To use this feature, a list of participants identifiers is required
50+
51+
```swift
52+
var identifiers : [CommunicationIdentifier] = []
53+
identifiers.append(CommunicationUserIdentifier("<USER_ID>"))
54+
identifiers.append(MicrosoftTeamsUserIdentifier("<USER_ID>"))
55+
spotlightFeature.startSpotlight(participants: identifiers, completionHandler: { (error) in
56+
if let error = error {
57+
print ("startSpotlight failed %@", error as Error)
58+
}
59+
})
60+
```
61+
62+
### Remove spotlight from participants
63+
Any pinned participant in the call or meeting can be unpinned. Only Microsoft 365 users who have an organizer, co-organizer or presenter role can unpin other participants. This action is idempotent, trying to stop spotlight on an unpinned participant does nothing
64+
65+
To use this feature, a list of participants identifiers is required
66+
```swift
67+
var identifiers : [CommunicationIdentifier] = []
68+
identifiers.append(CommunicationUserIdentifier("<USER_ID>"))
69+
identifiers.append(MicrosoftTeamsUserIdentifier("<USER_ID>"))
70+
spotlightFeature.stopSpotlight(participants: identifiers, completionHandler: { (error) in
71+
if let error = error {
72+
print ("stopSpotlight failed %@", error as Error)
73+
}
74+
})
75+
```
76+
77+
### Remove all spotlights
78+
All pinned participants can be unpinned using this API. Only MicrosoftTeamsUserIdentifier users who have an organizer, co-organizer or presenter role can unpin all participants.
79+
```swift
80+
spotlightFeature.stopAllSpotlight(completionHandler: { (error) in
81+
if let error = error {
82+
print ("stopAllSpotlight failed %@", error as Error)
83+
}
84+
})
85+
```
86+
87+
### Handle changed states
88+
The `Spotlight` API allows you to subscribe to `SpotlightChanged` events. A `SpotlightChanged` event comes from a `call` instance and contains information about newly spotlighted participants and participants whose spotlight were stopped
89+
```swift
90+
// event : { added: SpotlightedParticipant[]; removed: SpotlightedParticipant[] }
91+
// SpotlightedParticipant = { identifier: CommunicationIdentifier }
92+
// where:
93+
// identifier: ID of participant whos spotlight state is changed
94+
95+
spotlightFeature = self.call!.feature(Features.spotlight)
96+
spotlightFeature!.delegate = self.SpotlightDelegate
97+
98+
public class SpotlightDelegate: SpotlightCallFeatureDelegate {
99+
public func SpotlightCallFeature(_ spotlightCallFeature: SpotlightCallFeature, didChangeSpotlight args: SpotlightChangedEventArgs) {
100+
args.added.forEach { participant in
101+
print("Spotlight participant " + Utilities.toMri(participant.identifier) + "is ON")
102+
}
103+
args.removed.forEach { participant in
104+
print("Spotlight participant " + Utilities.toMri(participant.identifier) + "is OFF")
105+
}
106+
}
107+
}
108+
```
109+
110+
### Get all spotlighted participants:
111+
To get information about all participants that have spotlight state on current call, you can use the following API. The returned array is sorted by the order the participants were spotlighted.
112+
113+
``` swift
114+
spotlightCallFeature.spotlightedParticipants.forEach { participant in
115+
print("Spotlight active for participant: " + Utilities.toMri(participant.identifier))
116+
}
117+
```
118+
119+
### Get the maximum supported spotlight:
120+
The following API can be used to get the maximum number of participants that can be spotlighted using the Calling SDK
121+
``` swift
122+
spotlightCallFeature.maxSupported();
123+
```

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

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

10+
Communication Services or Microsoft 365 users can call the spotlight APIs based on role type and conversation type
11+
12+
**In a one to one call or group call scenario, the following APIs are supported for both Communication Services and Microsoft 365 users**
13+
14+
|APIs| Organizer | Presenter | Attendee |
15+
|----------------------------------------------|--------|--------|--------|
16+
| startSpotlight | ✔️ | ✔️ | ✔️ |
17+
| stopSpotlight | ✔️ | ✔️ | ✔️ |
18+
| stopAllSpotlight | ✔️ | ✔️ | ✔️ |
19+
| getSpotlightedParticipants | ✔️ | ✔️ | ✔️ |
20+
21+
**For meeting scenario the following APIs are supported for both Communication Services and Microsoft 365 users**
22+
23+
|APIs| Organizer | Presenter | Attendee |
24+
|----------------------------------------------|--------|--------|--------|
25+
| startSpotlight | ✔️ | ✔️ | |
26+
| stopSpotlight | ✔️ | ✔️ | ✔️ |
27+
| stopAllSpotlight | ✔️ | ✔️ | |
28+
| getSpotlightedParticipants | ✔️ | ✔️ | ✔️ |
29+
1030
Spotlight is an extended feature of the core `Call` API. You first need to import calling Features from the Calling SDK:
1131

1232
```js
@@ -26,7 +46,7 @@ spotLightFeature.startSpotlight();
2646
```
2747

2848
### Spotlight specific participants
29-
Any participant in the call or meeting can be pinned. Only Microsoft 365 users who have an organizer, coorganizer or presenter role can start spotlight for other participants. This action is idempotent, trying to start spotlight on a pinned participant does nothing
49+
Any participant in the call or meeting can be pinned. Only Microsoft 365 users who have an organizer, co-organizer or presenter role can start spotlight for other participants. This action is idempotent, trying to start spotlight on a pinned participant does nothing
3050
```js
3151
// Specify list of participants to be spotlighted
3252
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
@@ -43,7 +63,7 @@ spotLightFeature.stopSpotlight();
4363

4464

4565
### Remove spotlight from participants
46-
Any pinned participant in the call or meeting can be unpinned. Only Microsoft 365 users who have an organizer, coorganizer or presenter role can unpin other participants. This action is idempotent, trying to stop spotlight on an unpinned participant does nothing
66+
Any pinned participant in the call or meeting can be unpinned. Only Microsoft 365 users who have an organizer, co-organizer or presenter role can unpin other participants. This action is idempotent, trying to stop spotlight on an unpinned participant does nothing
4767
```js
4868
// Specify list of participants to be spotlighted
4969
CommunicationUserIdentifier acsUser = new CommunicationUserIdentifier(<USER_ID>);
@@ -52,7 +72,7 @@ spotLightFeature.stopSpotlight([acsUser, teamsUser]);
5272
```
5373

5474
### Remove all spotlights
55-
All pinned participants can be unpinned using this API. Only MicrosoftTeamsUserIdentifier users who have an organizer, coorganizer or presenter role can unpin all participants.
75+
All pinned participants can be unpinned using this API. Only MicrosoftTeamsUserIdentifier users who have an organizer, co-organizer or presenter role can unpin all participants.
5676
```js
5777
spotLightFeature.stopAllSpotLight();
5878
```

0 commit comments

Comments
 (0)