Merge pull request #1094 from Bandwidth/webrtc-v2

Updating In-App Calling Guide

site/global-guides/voice/inAppGuide.mdx

@@ -79,9 +79,19 @@ In order to place calls into the Bandwidth Network (and of course be subject to
 
 ### Generating credentials for an access token
 
-To generate an access token please contact your account manager and this will be provided to you. 
+To generate an access token you must first generate credentials that will allow you to call Bandwidth’s identity services endpoint. 
 
-Once you have received your credentials you can call our identity services endpoint. Please refer to here for more information.
+The following steps can be followed to generate your credentials:
+
+1. Login to the Global Portal
+2. Navigate to Settings > WebRTC Credentials
+    + If you do not see this option then your account has not been configured for In-App Calling. Please contact your account manager as referenced here.
+3. Click Generate Credentials
+4. The Client ID and Client Token will be displayed in a pop-up window. Please store these details securely. 
+
+![Generating WebRTC Credentials](@site/static/img/docs-diagrams/voice/in-app-credentials.png)
+
+Once you have generated your credentials you can call our identity services endpoint. Please refer to here for more information.
 
 :::note
 The scope must be **voice.webrtc** to generate an access token to use for in-app calling.
@@ -107,8 +117,144 @@ SDKs exposing all key capabilities are available in raw and packaged form.
 | Android / Kotlin    | Coming soon...                                                                          |
 | iOS / Swift         | Coming soon...                                                                          |
 
+### Supported Browsers
+
+The following table indicates the browsers and versions supported by the Bandwidth In-App Calling SDK.
+
+|            | Chrome                | Firefox               | Safari                | Edge                  |                 
+|:-----------|:----------------------|:----------------------|:----------------------|:----------------------|
+| Version    | 74+ (Chromium-based)  | 78+                   | 12+ (12.1 for iOS)    | 79+                   | 
+| Android    | ✓                     | ✓                     |                       |                       |
+| iOS        | ✓                     | ✓                     | ✓                     |                       |
+| Windows    | ✓                     | ✓                     |                       | ✓                     |
+| macOS      | ✓                     | ✓                     | ✓                     |                       |
+| Linux      | ✓                     | ✓                     |                       |                       |
+
 ### Sample Applications
 
 Getting started with Bandwidth’s In-App Calling SDKs is simple with sample applications to assist in the learning process.
 
-We will be publishing sample applications soon, please contact your Account Manager for help if required.
+We will be publishing sample applications soon, please contact your Account Manager for help if required.
+
+## In-App Calling SDK
+
+The key SDK functions are described in terms of the Javascript webrtc-browser SDK. Similar usage patterns show up in the Android and IOS client SDKs.
+
+There are two important classes in the WebRTC Client SDK - The User Agent (UA) and the Session. The UA is used to encapsulate the data and behaviors associated with the client itself, and the Session encapsulates actual in progress calls. A real world model would be the phone (UA) and calls made by the phone (Session).
+
+Initialization and management of the client, and the initiation of calls is managed by the UA, and once a call is in progress it can be altered by changes to the Session.
+
+### Client Initialization
+
+There are a number of key initialization steps that are required in the web client before the client is capable of placing calls. This ensures that:
+
++ The Client is appropriately configured, and capable of connecting to the WebRTC Gateway.
++ The account security token has been made available to the SDK to ensure that all calls will be associated with the correct account.
++ The events that will happen on active calls, and with the websocket connection can be appropriately intercepted by the client and handled.
++ The connection with the WebRTC Gateway can be established and removed.
+
+This is done by making changes to an instance of the UA with some of the methods described below.
+
+Once all of the above initialization steps have been completed, the client is in a position to place calls to the Bandwidth Network via the WebRTC Gateway, and respond to events from the network that result.
+
+The below methods on phone instances of the UA take care of readying the phone to make calls.
+
+#### phone.setServerConfig(serverAddresses, serverDomain, iceServers);
+
+The setServerConfig method takes 3 parameters that establish the relationship between the client and the network for making calls. This method should be called prior to any attempts to perform any other client or calling functions.
+
+There are three parameters for the setServerConfig method call:
+
+1. serverAddresses: List of the Bandwidth WebRTC gateway FQDN
+2. serverDomain: String containing the domain name to use in interactions with the WebRTC Gateway. This domain is a necessary portion of the endpoint addresses.
+3. iceServers: List of the STUN and TURN servers, containing STUN:// or TURN:// IP addresses. This optional parameter is by default set as an empty list []. If it is used as an empty list, an external STUN server is not used during the creation of the call. This mode is useful when the client has direct visibility of the public network IP addresses of the Bandwidth WebRTC Gateway.
+
+#### phone.setOAuthToken(token)
+
+All calls from web and mobile clients require a security token generated by Bandwidth to be present with any request to establish a call to the Bandwidth Network. The setOAuthToken method invoked on an instance of the UA will cause this token to be registered with the client, and used in subsequent calls to ensure that the calls are authentic and contain the correct account information.
+
+There is a single parameter that is required for the setOAuthToken method - a string containing the Token that was previously fetched from Bandwidth.
+
+1. Token: a string containing the Token minted by Bandwidth to secure the traffic from the client. 
+
+The token is cryptographically protected from tampering, and establishes the account ownership of the customer application, ensuring that our customers will only be presented and billed for traffic that they have authorized.
+
+#### phone.setListeners()
+
+There is little value in sending a call towards the Bandwidth network if there is no feedback on events that happen in the network while completing the call. The setListeners UA method allows the registration of callback functions that (if registered) will be invoked on various network and connection events, allowing the client to respond to normal and error conditions that are encountered in the network.
+
+The setListeners configuration method is invoked on an instance of the UA, and has a single listeners object as the parameter. This listener object contains six or more elements, each of which is a function that will be invoked on the detection of the event in the network. These functions will be described in greater detail elsewhere.
+
+The individual functions that can be provided in the listeners object are...
+
+1. loginStateChanged: function(isLogin, cause)
+    + The provided function is invoked when the connection state between the Bandwidth WebRTC server and the Client changes. This can occur when a requested connection is established in a bi-directional manner, or when that connection fails. There are other causes of this event that will be documented elsewhere.
+2. outgoingCallProgress: function(call, response)
+    + The provided function is invoked when there is a change in the state of the call from the client. A classic example of this is when a ringing state is detected.
+3. callTerminated: function(call, message, cause)
+    + the provided function is invoked when the call ends. A cause for the end of the call is provided.
+4. callConfirmed: function(call, message, cause)
+    + The provided function is invoked when the system has determined that the call has been accepted by the Bandwidth WebRTC gateway, and further progress of the call is anticipated.
+5. callShowStreams: function(call, localStream, remoteStream)
+    + The provided function is invoked when media streams have been established. This often corresponds with the answering of the call.
+6. callHoldStateChanged(call, isHold, isRemote)
+    + If the system is configured to support hold state conditions, this function will be invoked on changes in the hold state of the call.
+
+#### phone.init()
+
+The init method is used to establish the connection to the Bandwidth WebRTC gateway. This method is only valid once the UA has been configured.
+
+#### phone.deinit()
+
+The deinit method reverses the action of the init method, removing the connection between the client and the Bandwidth WebRTC gateway.
+
+#### phone.isInitialized()
+
+Checks if the init() method was called.
+
+#### phone.checkAvailableDevices()
+
+This method has two functions:  
+
++ Checks if the WebRTC API is supported in the used browser. 
+    + If this is not supported, the Promise object will be rejected with the following string: “WebRTC is not supported in the browser”. 
++ Checks available devices (speaker, microphone and camera). 
+    + If the speaker is not connected, the speaker Promise object is rejected with the following string: “Missing a speaker! Please connect one and reload” 
+    + If the microphone is not connected, the microphone is rejected with the following string: “Missing a microphone! Please connect one and reload”
+
+### Managing Calls from the Client
+
+Once the UA has been configured and the connection to the Bandwidth WebRTC Gateway has been established, it is time to make and manage calls. Once the setup is done, the rest is relatively straightforward.
+
+#### activeCall = phone.call(phone.AUDIO, tn)
+
+The call method invoked on the UA instance will cause the configured and connected UA to launch a call towards the Bandwidth network. Yes - it is that simple.
+
+The call method takes two parameters:
+
+1. The first parameter reflects the desired media, and as a result of the nature of the Bandwidth Voice network, this parameter must be supplied with the argument "phone.AUDIO" where the 'phone' represents the instance of the UA that has been created and configured. This parameter may be used in the future to extend the capabilities to other media.
+2. The second parameter represents the destination telephone number for the outbound call. This TN should be a valid NANP telephone number.
+
+The call method returns an instance of a Session object, providing a handle that can be used for subsequent modification of the call while it is in progress. The methods applicable to the Session object instance will be discussed below.
+
+In the sections below, the string activeCall will represent the Session instance used for subsequent call modifications.
+
+#### activeCall.terminate();
+
+Once a call has been established, one of the possible call modification actions is to end (or terminate) the call. The terminate method on the Session object will be used to cause the call to end.
+
+#### activeCall.sendDTMF(digit)
+
+If a session represents a call that has established an end-to-end connection, the sendDTMF method will cause a specified DTMF tone to the far end of the call connection. The digit parameter is single character string containing a character from the set [0-9,#,*]. This action is undefined if there is no audio connection to the destination of the call.
+
+#### activeCall.hold(placeCallOnHold)
+
+If a session represents a call that has established an end-to-end connection, the hold method places the call on a (local) hold, or removes it from a hold state if it is currently held. The single boolean parameter indicates that the call is to be held (true) or removed from hold (false). This action is undefined if there is no audio connection to the destination of the call.
+
+#### activeCall.muteAudio(muted)
+
+Once a call has been established, this method could be used to mute the audio.
+
+#### activeCall.isLocalHold() 
+
+Returns a boolean value indicating whether the call is currently held as the result of an activeCall.hold(true) action.