Skip to content

Commit

Permalink
Add mobile SDK MeetingSessionStatusCode handling to FAQ (#2890)
Browse files Browse the repository at this point in the history 
* Add mobile SDK MeetingSessionStatusCode handling to FAQ

* Add "How to reproduce each MeetingSessionStatusCode" to mobile FAQ
  • Loading branch information
@georgezy-amzn
georgezy-amzn authored Jun 10, 2024
1 parent 290c6cb commit c6254b8
Show file tree
Hide file tree
Showing 2 changed files with 290 additions and 3 deletions.
231 changes: 229 additions & 2 deletions docs/modules/faqs.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,13 @@ <h1>Frequently Asked Questions</h1>
<li><a href="#how-do-i-receive-amazon-chime-sdk-channel-messages-without-using-the-amazon-chime-sdk-for-javascript">How do I receive Amazon Chime SDK channel messages without using the Amazon Chime SDK for JavaScript?</a></li>
</ul>
</li>
<li><a href="#mobile-sdk">Mobile SDK</a><ul>
<li><a href="#how-to-determine-if-a-meeting-session-stop-will-be-self-recoverable-or-terminal">How to determine if a meeting session stop will be self-recoverable or terminal?</a></li>
<li><a href="#what-does-each-meetingsessionstatuscode-mean">What does each <code>MeetingSessionStatusCode</code> mean?</a></li>
<li><a href="#how-should-i-handle-each-meetingsessionstatuscode-in-my-application">How should I handle each <code>MeetingSessionStatusCode</code> in my application?</a></li>
<li><a href="#how-to-reproduce-each-meetingsessionstatuscode">How to reproduce each <code>MeetingSessionStatusCode</code>?</a></li>
</ul>
</li>
</ul>
</li>
</ul>
Expand Down Expand Up @@ -674,8 +681,228 @@ <h2>Messaging</h2>
<h3>How do I receive Amazon Chime SDK channel messages without using the Amazon Chime SDK for JavaScript?</h3>
</a>
<p>Follow the instructions in the <a href="https://docs.aws.amazon.com/chime-sdk/latest/dg/websockets.html#connect-api">&quot;Using websockets to receive messages&quot; developer guide</a>.
To sign the URL in Python, use the example code in the <a href="https://github.com/aws/amazon-chime-sdk-js/issues/1241#issuecomment-830705541">GitHub issue #1241</a>.
<a href="https://github.com/aws/amazon-chime-sdk-js/issues/new?assignees=&amp;labels=documentation&amp;template=documentation-request.md&amp;title=FAQs%20feedback">Give feedback on this guide</a></p>
To sign the URL in Python, use the example code in the <a href="https://github.com/aws/amazon-chime-sdk-js/issues/1241#issuecomment-830705541">GitHub issue #1241</a>.</p>
<a href="#mobile-sdk" id="mobile-sdk" style="color: inherit; text-decoration: none;">
<h2>Mobile SDK</h2>
</a>
<a href="#how-to-determine-if-a-meeting-session-stop-will-be-self-recoverable-or-terminal" id="how-to-determine-if-a-meeting-session-stop-will-be-self-recoverable-or-terminal" style="color: inherit; text-decoration: none;">
<h3>How to determine if a meeting session stop will be self-recoverable or terminal?</h3>
</a>
<p>Your application should not rely on <code>MeetingSessionStatusCode</code> for determining if the session stop is self-recoverable or terminal, instead, your should subscribe to <code>AudioVideoObserver</code> callbacks. When a self-recoverable session stop happens(i.e. caused by a poor network connection), <code>AudioVideoObserver.audioSessionDidDrop()</code> will be triggered, and Chime SDK will retry connecting automatically, if the session is successfully reconnected, <code>AudioVideoObserver.audioSessionDidStart(reconnecting: true)</code> will be triggered, your application should start handling the success of the reonnecting at this point; when a terminal session stop happens or retries have been exhausted, <code>AudioVideoObserver.audioSessionDidStopWithStatus(MeetingSessionStatus)</code> will be triggered, in this case any further retry will not be helpful, you application should handle the session stop accordingly based on the <code>MeetingSessionStatusCode</code>, and notify user if needed.</p>
<a href="#what-does-each-meetingsessionstatuscode-mean" id="what-does-each-meetingsessionstatuscode-mean" style="color: inherit; text-decoration: none;">
<h3>What does each <code>MeetingSessionStatusCode</code> mean?</h3>
</a>
<p>The definition of each <code>MeetingSessionStatusCode</code> can be found <a href="https://aws.github.io/amazon-chime-sdk-ios/Enums/MeetingSessionStatusCode.html">here</a> for iOS and <a href="https://aws.github.io/amazon-chime-sdk-android/amazon-chime-sdk/com.amazonaws.services.chime.sdk.meetings.session/-meeting-session-status-code/index.html">here</a> for Android.</p>
<a href="#how-should-i-handle-each-meetingsessionstatuscode-in-my-application" id="how-should-i-handle-each-meetingsessionstatuscode-in-my-application" style="color: inherit; text-decoration: none;">
<h3>How should I handle each <code>MeetingSessionStatusCode</code> in my application?</h3>
</a>
<p><code>MeetingSessionStatusCode</code> provides additional details for the MeetingSessionStatus received for a session. The primary use is in callbacks of AudioVideoObserver. Specifically, they are utilized in <code>AudioVideoObserver.audioSessionDidStopWithStatus(MeetingSessionStatus)</code>/<code>AudioVideoObserver.videoSessionDidStartWithStatus(MeetingSessionStatus)</code>/<code>AudioVideoObserver.videoSessionDidStopWithStatus(MeetingSessionStatus)</code> for iOS, and their equivalents for Android. There are also usages in ReplicatedMeetings, they have been documented separately(<a href="https://github.com/aws/amazon-chime-sdk-ios/blob/master/guides/replicated_meetings.md">iOS</a>/<a href="https://github.com/aws/amazon-chime-sdk-android/blob/master/guides/replicated_meetings.md">Android</a>).</p>
<p>These status codes can be used for logging, debugging, and notification to end users, but in most cases should not be used for any retry behavior, as Chime SDK will already be retrying non-terminal errors. The table below illustrates how each code should be handled.</p>
<table>
<thead>
<tr>
<th><code>MeetingSessionStatusCode</code></th>
<th>Callbacks</th>
<th>How to handle</th>
</tr>
</thead>
<tbody><tr>
<td>OK(iOS/Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code> <code>videoSessionDidStartWithStatus(MeetingSessionStatus)</code> <code>videoSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>This code indicates the audio/video sessions on the device have been started/stopped without any errors. When received from AudioVideoObserver callbacks, your application may want to notify your user about the success of session start/stop.</td>
</tr>
<tr>
<td>Left(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code> <code>videoSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>It indicates the meeting session on the device has been disconnected due to the attendee leave, nothing to handle except notify your application user about the session stop.</td>
</tr>
<tr>
<td>networkBecomePoor(iOS) NetworkBecamePoor(Android)</td>
<td><code>connectionDidBecomePoor()</code></td>
<td>Your application not be receiving this code directly, <code>AudioVideoObserver.connectionDidBecomePoor()</code> will be triggered instead. You can subscribe to this callback and notify your application user about the network issue, however, you should not retry connect the meeting session, Chime SDK will handle it. When retries are exhausted, the meeting session will stop completely, <code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code> will be triggered then.</td>
</tr>
<tr>
<td>audioServerHungup(iOS) audioServiceUnavailable(iOS) AudioServiceUnavailable(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>There is an issue with Amazon Chime SDK service itself, the meeting session on the device has been terminated at this point, you will not be able to rejoin, your application should notify user about the session termination. Depends on your application design/user-flow, you could re-try/re-join the session, however, this may not work if the issue is not transient.</td>
</tr>
<tr>
<td>audioJoinedFromAnotherDevice(iOS) AudioJoinedFromAnotherDevice(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>The attendee joined the meeting from another device. The meeting session on current device has been disconnected, your application should not retry connecting.</td>
</tr>
<tr>
<td>audioInternalServerError(iOS)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>When received the code from the callback, the meeting session on the device has been terminated due to audio issues, the issue could be audio device related, or with Amazon Chime SDK service itself, you will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
<tr>
<td>audioAuthenticationRejected(iOS) AudioAuthenticationRejected(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>When received this code from the callback, the meeting session on the device has been terminated because the attendee information is invalid, you will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
<tr>
<td>audioCallAtCapacity(iOS) AudioCallAtCapacity(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>When received this code from the callback, the meeting session on the device has been terminated due to the meeting is at full capacity, the service supports up to 250 attendees. You will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
<tr>
<td>audioDisconnectAudio(iOS) AudioDisconnectAudio(Android) connectionHealthReconnect(iOS) ConnectionHealthReconnect(Android)</td>
<td>None</td>
<td>This is only used internally by the AWS service and will not be provided in any AudioVideoObserver callbacks.</td>
</tr>
<tr>
<td>audioCallEnded(iOS) AudioCallEnded(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>The meeting session has been ended on Amazon Chime SDK service side. When received this code from the callback, the meeting session on the device has been terminated, you will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
<tr>
<td>videoServiceUnavailable(iOS) VideoServiceFailed(Android)</td>
<td><code>videoSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>There was an internal server error related to video. This may indicate some issue with the camera device, or an issue with the Amazon Chime SDK service itself. When received thie code from the callback, you will not be able to join the video session, however, the audio session may still be working. Your application should notify user about the video session termination.</td>
</tr>
<tr>
<td>videoAtCapacityViewOnly(iOS) VideoAtCapacityViewOnly(Android)</td>
<td><code>videoSessionDidStartWithStatus(MeetingSessionStatus)</code></td>
<td>When received thie code from the callback, it indicates the video session on the device is in &quot;receive only&quot; mode due to capacity reached. Your local video source will not be sent to other attendess, however, you will still be able to receive video streams from other attendees.</td>
</tr>
<tr>
<td>audioInputDeviceNotResponding(iOS) AudioOutputDeviceNotResponding(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>When receveid this code from the callback, it indicates the meeting session on the device has been terminated due to audio input device related issues. You will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
<tr>
<td>audioOutputDeviceNotResponding(iOS) AudioInputDeviceNotResponding(Android)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>When receveid this code from the callback, it indicates the meeting session on the device has been terminated due to audio output device related issues. You will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
<tr>
<td>unknown(iOS)</td>
<td><code>audioSessionDidStopWithStatus(MeetingSessionStatus)</code></td>
<td>When received this code from the callback, it indicates the meeting session has been terminated due to an status that the mobile SDK is not able to map. You will not be able to rejoin the meeting, your application should notify user about the session termination.</td>
</tr>
</tbody></table>
<a href="#how-to-reproduce-each-meetingsessionstatuscode" id="how-to-reproduce-each-meetingsessionstatuscode" style="color: inherit; text-decoration: none;">
<h3>How to reproduce each <code>MeetingSessionStatusCode</code>?</h3>
</a>
<p>Below is the list of <code>MeetingSessionStatusCode</code> that you can reproduce for each AudioVideoObserver callback, please note some of the codes(i.e., audioServiceUnavailable) due to Amazon Chime SDK service issues, which cannot be reproduced on mobile Chime SDK client.</p>
<table>
<thead>
<tr>
<th><code>MeetingSessionStatusCode</code></th>
<th>audioSessionDidStopWithStaus()</th>
<th>videoSessionDidStartWithStatus()</th>
<th>videoSessionDidStopWithStatus()</th>
<th>connectionDidBecomePoor()</th>
</tr>
</thead>
<tbody><tr>
<td>OK(iOS/Android)</td>
<td>During a valid call session, call meetingsession.audioVideo.stop().</td>
<td>With a valid meeting join info, call meetingSession.audioVideo.start().</td>
<td>During a valid call session, call meetingsession.audioVideo.stop().</td>
<td>N/A</td>
</tr>
<tr>
<td>Left(Android)</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>networkBecomePoor(iOS) NetworkBecamePoor(Android)</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
<td>During a valid call session, disconnect the network on your iOS/Android device.</td>
</tr>
<tr>
<td>audioServerHungup(iOS) audioServiceUnavailable(iOS) AudioServiceUnavailable(Android)</td>
<td>Chime SDK service issue, cannot be reproduced on your mobile device.</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioJoinedFromAnotherDevice(iOS) AudioJoinedFromAnotherDevice(Android)</td>
<td>During a valid call session, use the same meeting join info to join the call on another device, the callback will be called on the original device.</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioInternalServerError(iOS)</td>
<td>Chime SDK service issue, cannot be reproduced on mobile device.</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioAuthenticationRejected(iOS) AudioAuthenticationRejected(Android)</td>
<td>Use an invalid join token(<a href="https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Attendee.html#chimesdk-Type-meeting-chime_Attendee-JoinToken">link</a>) to join the call.</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioCallAtCapacity(iOS) AudioCallAtCapacity(Android)</td>
<td>Start a Chime call session, have 250 attendee join the session, get another attendee to join the session, you will get this code. This does not apply to Amazon Connect use case.</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioDisconnectAudio(iOS) AudioDisconnectAudio(Android) connectionHealthReconnect(iOS) ConnectionHealthReconnect(Android)</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioCallEnded(iOS) AudioCallEnded(Android)</td>
<td>N/A (Not being used)</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>videoServiceUnavailable(iOS) VideoServiceFailed(Android)</td>
<td>N/A</td>
<td>Chime SDK service issue, cannot be reproduced on mobile device.</td>
<td>Chime SDK service issue, cannot be reproduced on mobile device.</td>
<td>N/A</td>
</tr>
<tr>
<td>videoAtCapacityViewOnly(iOS) VideoAtCapacityViewOnly(Android)</td>
<td>N/A</td>
<td>Ttart a Chime call session, have 25 attendee join the session and start their videos, get another attendee to join the session, you will get this code. This does not apply to Amazon Connect use case.</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioInputDeviceNotResponding(iOS) AudioOutputDeviceNotResponding(Android)</td>
<td>This is due to audio input stream not starting properly, unable to reproduce this code, maybe try to physically disable your mic...</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>audioOutputDeviceNotResponding(iOS) AudioInputDeviceNotResponding(Android)</td>
<td>This is due to audio input stream not starting properly, unable to reproduce this code, maybe try to physically disable your mic...</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
<tr>
<td>unknown(iOS)</td>
<td>This will be returned when there is an code that mobile SDK is not able to handle, currently if you disable the network connection on your device, wait for the reconnect exhausts</td>
<td>N/A</td>
<td>N/A</td>
<td>N/A</td>
</tr>
</tbody></table>
<p><a href="https://github.com/aws/amazon-chime-sdk-js/issues/new?assignees=&amp;labels=documentation&amp;template=documentation-request.md&amp;title=FAQs%20feedback">Give feedback on this guide</a></p>
</div>
</section>
</div>
Expand Down
Loading

0 comments on commit c6254b8

Please sign in to comment.