Skip to content

Commit 943be15

Browse files
amagginettiamagginetti
committed
test
1 parent 5283500 commit 943be15

File tree

1 file changed

+85
-54
lines changed

1 file changed

+85
-54
lines changed

‎articles/communication-services/tutorials/end-of-call-survey-tutorial.md

Lines changed: 85 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -37,101 +37,136 @@ This tutorial shows you how to use the Azure Communication Services End of Call
3737
- An active Communication Services resource. [Create a Communication Services resource](../quickstarts/create-communication-resource.md). Survey results are tied to single Communication Services resources.
3838
- An active Log Analytics Workspace, also known as Azure Monitor Logs, to ensure you do not lose your survey results. [Enable logging in Diagnostic Settings](../concepts/analytics/enable-logging.md).
3939

40-
<!-- need to update the version after beta release -->
40+
4141
> [!IMPORTANT]
4242
> End of Call Survey is available starting on the version [1.13-beta.1](https://www.npmjs.com/package/@azure/communication-calling/v/1.13-beta.1) of the Calling SDK. Make sure to use that version or later when trying the instructions.
4343
44-
### Sample of API usage
44+
## Sample of API usage
45+
46+
We encourage you to use the default rating scale. However, you have the option to submit a survey with custom rating scale. You can check out the [sample application](https://github.com/Azure-Samples/communication-services-web-calling-tutorial/blob/main/Project/src/MakeCall/CallSurvey.js) for the complete API usage. You will need the call object to submit the call survey. You will have the call object when you start or receive a call. The code snip below shows an example of one-to-one call. After the end of the call, show the survey option.
4547

4648

49+
```typescript
50+
const call: Call = callAgent.startCall(['{target participant / callee MRI / number}']);
51+
call.on('stateChanged', callStateChangedHandler);
52+
const callStateChangedHandler = () => {
53+
if (call.state === 'Disconnected') {
54+
console.log('call end reason', call.callEndReason);
55+
// TODO: Show the UI to collect the survey data
56+
}
57+
};
58+
```
4759

60+
When the participant submits the survey, then call the submit survey API with survey data.
4861

49-
#### Rate call only - no custom data
62+
### Rate call only - no custom scale
5063

5164
```javascript
5265
call.feature(Features.CallSurvey).submitSurvey({
53-
overallRating: { score: 3 }
54-
}).then(() => console.log('survey submitted successfully'))
66+
overallRating: { score: 5 }, // issues are optional
67+
videoRating: { score: 4, issues: ['LowQuality'] },
68+
screenshareRating: { score: 4, issues: ['LargeDelay'] }
69+
}).then(() => console.log('survey submitted successfully'));
5570
```
5671

72+
At least one of the four categories (overallRating, audioRating, videoRating or screenshareRating) is required.
5773

5874

75+
### Rate call only - with custom scale and issues
5976

60-
#### Rate call only - with custom scale
61-
``` javascript
77+
```javascript
6278
call.feature(Features.CallSurvey).submitSurvey({
63-
overallRating: {
64-
score: 1, // my score
65-
scale: { // my custom scale
66-
lowerBound: 0,
67-
upperBound: 2,
68-
lowScoreThreshold: 1
69-
},
70-
issues: ['HadToRejoin'] // my issues
71-
}
72-
}).then(() => console.log('survey submitted successfully'))
79+
overallRating: {
80+
score: 1, // my score
81+
scale: { // my custom scale
82+
lowerBound: 0,
83+
upperBound: 1,
84+
lowScoreThreshold: 0
85+
},
86+
issues: ['HadToRejoin'] // my issues, check the table below for all available issues
87+
}
88+
}).then(() => console.log('survey submitted successfully'));
7389
```
7490

75-
#### Rate audio / video call with sample issue
91+
### Rate audio / video call with sample issue
7692
``` javascript
7793
call.feature(Features.CallSurvey).submitSurvey({
78-
overallRating: { score: 3 },
79-
audioRating: { score : 4 },
80-
videoRating: { score : 3, issues: ['Freezes'] }
81-
}).then(() => console.log('survey submitted successfully'))
94+
overallRating: { score: 3 },
95+
audioRating: { score: 4 },
96+
videoRating: { score: 3, issues: ['Freezes'] }
97+
}).then(() => console.log('survey submitted successfully'))
8298
```
83-
#### Handle errors that the SDK can throw
84-
```javascript
99+
100+
### Handle Errors that SDK can throw
101+
``` javascript
85102
call.feature(Features.CallSurvey).submitSurvey({
86-
overallRating: { score: 3 }
87-
}).catch((e) => console.log('error when submitting survey: ' + e ))
103+
overallRating: { score: 3 }
104+
}).catch((e) => console.log('error when submitting survey: ' + e))
88105
```
89106

90-
### Check for different types of errors
107+
108+
109+
## Find different types of errors
110+
111+
### Failures while submitting survey:
112+
113+
API will return the error messages when data validation failed or unable to submit the survey.
91114
- At least one survey rating is required.
92115
- In default scale X should be 1 to 5. - where X is either of
93-
- overallRating.score
94-
- audioRating.score
95-
- videoRating.score
96-
- screenshareRating.score
116+
- overallRating.score
117+
- audioRating.score
118+
- videoRating.score
119+
- screenshareRating.score
97120
- ${propertyName}: ${rating.score} should be between ${rating.scale?.lowerBound} and ${rating.scale?.upperBound}. ;
98121
- ${propertyName}: ${rating.scale?.lowScoreThreshold} should be between ${rating.scale?.lowerBound} and ${rating.scale?.upperBound}. ;
99122
- ${propertyName} lowerBound: ${rating.scale?.lowerBound} and upperBound: ${rating.scale?.upperBound} should be between 0 and 100. ;
100-
- event discarded ACS failed to submit survey
101-
102-
123+
- event discarded [ACS failed to submit survey, due to network or other error]
103124

104-
## Collect survey data
125+
## All possible values
105126

106-
> [!IMPORTANT]
107-
> You must enable a Diagnostic Setting in Azure Monitor to send the log data of your surveys to a Log Analytics workspace, Event Hubs, or an Azure storage account to receive and analyze your survey data. If you do not send survey data to one of these options your survey data will not be stored and will be lost. To enable these logs for your Communications Services, see: [Enable logging in Diagnostic Settings](../concepts/analytics/enable-logging.md)
108-
127+
### Default survey API configuration
109128

110-
### View survey data with a Log Analytics workspace
111-
112-
You need to enable a Log Analytics Workspace to both store the log data of your surveys and access survey results. To enable these logs for your Communications Services, see: [Enable logging in Diagnostic Settings](../concepts/analytics/enable-logging.md). Follow the steps to add a diagnostic setting. Select the “CALL DIAGNOSTICS???” data source when choosing category details. Also, choose “Send to Log Analytics workspace” as your destination detail.
129+
| API Rating Categories | Cutoff Value* | Input Range | Comments |
130+
| ----------- | ----------- | -------- | -------- |
131+
| Overall Call | 2 | 1 - 5 | Surveys a calling participant’s overall quality experience on a scale of 1-5 where 1 indicates an imperfect call experience and 5 indicates a perfect call. The cutoff value of 2 means that a customer response of 1 or 2 indicates a less than perfect call experience. |
132+
| Audio | 2 | 1 - 5 | A response of 1 indicates an imperfect audio experience and 5 indicates no audio issues were experienced. |
133+
| Video | 2 | 1 - 5 | A response of 1 indicates an imperfect video experience and 5 indicates no video issues were experienced. |
134+
| Screenshare | 2 | 1 - 5 | A response of 1 indicates an imperfect screen share experience and 5 indicates no screen share issues were experienced. |
113135

114-
- You can also integrate your Log Analytics workspace with Power BI, see: [Integrate Log Analytics with Power BI](../../../articles/azure-monitor/logs/log-powerbi.md)
115136

137+
### Additional survey tags
138+
| Rating Categories | Optional Tags |
139+
| ----------- | ----------- |
140+
| Overall Call | `CallCannotJoin` `CallCannotInvite` `HadToRejoin` `CallEndedUnexpectedly` `OtherIssues` |
141+
| Audio | `NoLocalAudio` `NoRemoteAudio` `Echo` `AudioNoise` `LowVolume` `AudioStoppedUnexpectedly` `DistortedSpeech` `AudioInterruption` `OtherIssues` |
142+
| Video | `NoVideoReceived` `NoVideoSent` `LowQuality` `Freezes` `StoppedUnexpectedly` `DarkVideoReceived` `AudioVideoOutOfSync` `OtherIssues` |
143+
| Screenshare | `NoContentLocal` `NoContentRemote` `CannotPresent` `LowQuality` `Freezes` `StoppedUnexpectedly` `LargeDelay` `OtherIssues` |
116144

117-
### Default survey analytics queries
118145

119-
You can use the following sample query in your Log Analytics workspace or Power BI.
146+
### Customization options
120147

121148

122-
### Export survey data
149+
| API Rating Categories | Cutoff Value* | Input Range |
150+
| ----------- | ----------- | -------- |
151+
| Overall Call | 0 - 100 | 0 - 100 |
152+
| Audio | 0 - 100 | 0 - 100 |
153+
| Video | 0 - 100 | 0 - 100 |
154+
| Screenshare | 0 - 100 | 0 - 100 |
123155

124-
If you want to export your survey data, you can instead choose to send the log data of your surveys to Event Hubs, see: [Enable logging in Diagnostic Settings](../concepts/analytics/enable-logging.md). Follow the steps to add a diagnostic setting. Again, select the “CALL DIAGNOSTICS???” data source when choosing category details. Then, choose “Stream to an event hub” as your destination detail.
156+
- ***Note**: A question’s indicated cutoff value in the API is the threshold that Microsoft uses when analyzing your survey data. When you customize the cutoff value or Input Range, Microsoft analyzes your survey data according to your customization.
125157

126-
You can only view your survey data if you have enabled a Diagnostic Setting to capture your survey data. To learn how to use the End of Call Survey and view your survey data, see: **Tutorial Link**
127158

128-
### Survey data format
159+
## Collect survey data
129160

130-
Survey data will be in the following table format in the ranges and values that were submitted.
161+
> [!IMPORTANT]
162+
> You must enable a Diagnostic Setting in Azure Monitor to send the log data of your surveys to a Log Analytics workspace, Event Hubs, or an Azure storage account to receive and analyze your survey data. If you do not send survey data to one of these options your survey data will not be stored and will be lost. To enable these logs for your Communications Services, see: [Enable logging in Diagnostic Settings](../concepts/analytics/enable-logging.md)
163+
131164

165+
### View survey data with a Log Analytics workspace
132166

167+
You need to enable a Log Analytics Workspace to both store the log data of your surveys and access survey results. To enable these logs for your Communications Services, see: [Enable logging in Diagnostic Settings](../concepts/analytics/enable-logging.md). Follow the steps to add a diagnostic setting. Select the “ACSCallSurvey” data source when choosing category details. Also, choose “Send to Log Analytics workspace” as your destination detail.
133168

134-
## Debug support?
169+
- You can also integrate your Log Analytics workspace with Power BI, see: [Integrate Log Analytics with Power BI](../../../articles/azure-monitor/logs/log-powerbi.md)
135170

136171

137172
## Best Practices
@@ -155,12 +190,8 @@ Surveying Guidelines
155190
- The order of your questions matters. We recommend you randomize the sequence of optional tags in Question 2 in case respondents focus most of their feedback on the first prompt they visually see.
156191
- Consider using surveys for separate ACS Resources in controlled experiments to identify release impacts.
157192

158-
## Frequently Asked Questions (FAQs)
159-
- When can I use the API?
160-
- How long will it take for survey data to be available in Azure?
161193

162194
## Next Steps
163-
- Learn more about the End of Call Survey, see:
164195

165196
- Learn how to use the Log Analytics workspace, see: [Log Analytics Tutorial](../../../articles/azure-monitor/logs/log-analytics-tutorial.md)
166197

0 commit comments

Comments
 (0)