Adding In-App Calling Guide (#1091)

* Adding In-App Calling Guide Page * Fixed sidebar * Added links * Added table and how it works image * Basic formatting * Updated phone numbers section * Added deprecation message * Updated sidebar * Changed 2024 message * Small refinements * SWI-2948 Add Section For Global Guides (#1062) * SWI-2948 Add Section For Global Guides * update cypress tests --------- Co-authored-by: AJ Rice <[email protected]> * Testing new global guide * Updated global guide * Fixed sidebar, intro and deprecation message. * Updated links --------- Co-authored-by: Cameron Koegel <[email protected]> Co-authored-by: AJ Rice <[email protected]>
Bandwidth · Jul 19, 2023 · 11bee22 · 11bee22
1 parent 6058702
commit 11bee22
Show file tree

Hide file tree

Showing 9 changed files with 206 additions and 24 deletions.
diff --git a/site/cypress/e2e/tests/navbar.cy.js b/site/cypress/e2e/tests/navbar.cy.js
@@ -7,25 +7,30 @@ context('The Home Page', () => {
 })
 
 context('Docs', () => {
-  navBarContext('Guides');
+  navBarContext('US & Canada', 'Guides');
   navTester('docs');
 })
 
 context('API Reference', () => {
-  navBarContext('API Reference');
+  navBarContext('US & Canada', 'API Reference');
   navTester('apis')
 })
 
 context('SDKs', () => {
-  navBarContext('SDKs');
+  navBarContext('US & Canada', 'SDKs');
   navTester('sdks')
 })
 
-context('Global Docs and API Ref', () => {
-  navBarContext('Docs & API Reference')
+context('Global API Ref', () => {
+  navBarContext('Global', 'API Reference')
   navTester('apis/global')
 })
 
+context('Global Docs', () => {
+  navBarContext('Global', 'Guides')
+  navTester('global-guides')
+})
+
 context('Bandwidth Sample', () => {
 it('Should verify the external link worked', () => {
   cy.visit('/')

diff --git a/site/cypress/e2e/tests/viewport.cy.js b/site/cypress/e2e/tests/viewport.cy.js
@@ -1,15 +1,21 @@
 import {navBarContext} from '../../utils/utils'
 
-context('Should verify that Responsive CSS changes happen when the viewport changes sufficently', () => {
+context('Should verify that Responsive CSS changes happen when the viewport changes sufficiently', () => {
   beforeEach(() => {
     cy.visit('/')
   })
 
   it('Verify that US & Canada navbar menu is hidden when screen size is small', () => {
-    navBarContext('US & Canada', true, 320, 480)
+    cy.viewport(320,480)
+    cy.get('a.navbar__link')
+    .contains(`US & Canada`)
+    .should('be.hidden')
   })
 
   it('Verify that Global APIs navbar menu is hidden when screen size is small', () => {
-    navBarContext('Global APIs', true, 320, 480)
+    cy.viewport(320,480)
+    cy.get('a.navbar__link')
+    .contains(`Global`)
+    .should('be.hidden')
   })
 })
diff --git a/site/cypress/utils/utils.js b/site/cypress/utils/utils.js
@@ -1,22 +1,18 @@
 
-export const navBarContext = (pathName, hidden, viewportWidth = 1400, viewportHeight = 900) => {
+export const navBarContext = (context, pathName, viewportWidth = 1400, viewportHeight = 900) => {
   it('checks that navigation back or forward in the browser\'s history from the page works', () => {
     cy.visit('/')
     if (viewportWidth && viewportHeight) {
       cy.viewport(viewportWidth,viewportHeight)
-      if (hidden) {
-        cy.get('a.navbar__link')
-        .contains(`${pathName}`)
-        .should('be.hidden')
-      }
-      else {
-        cy.get('ul.dropdown__menu > li')
-        .should('be.hidden')
-        .invoke('show')
-        .get('a.dropdown__link')
-        .contains(`${pathName}`)
-        .click({force: true})
-      }
+      cy.get('a.navbar__link')
+      .contains(context)
+      .siblings()
+      .children()
+      .should('be.hidden')
+      .invoke('show')
+      .children()
+      .contains(pathName)
+      .click({force: true})
     }
  })
 }

diff --git a/site/docs/webrtc/about.mdx b/site/docs/webrtc/about.mdx
@@ -1,6 +1,6 @@
 ---
 id: about
-title: WebRTC
+title: (Deprecated) WebRTC
 sidebar_label: Overview
 slug: /webrtc
 description: A general overview of Bandwidth's account services
@@ -16,6 +16,14 @@ export const Svg = require('@site/static/img/product-icons/webrtc.svg').default;
 
 <Svg className='about-image'/> <br/>
 
+:::note
+Effective May 5, 2023, Bandwidth’s WebRTC API is no longer available for purchase. Check out [In-App Calling](/global-guides/voice/guides/inAppCalling/) for our new, simplified solution to enable WebRTC voice calls within a browser or mobile app.
+
+Bandwidth customers who are currently using the WebRTC API product may continue doing so until further notice, referring to these dev docs as is useful.
+
+Existing customers looking to migrate from the WebRTC API to the new In-App Calling product should get in touch with their Bandwidth account manager!
+:::
+
 ## An Intro to WebRTC
 
 WebRTC is technology that allows browsers and other devices to interact and communicate with each other in real-time. Browsers using WebRTC do not need extra plug-ins or downloads -- it all works natively in the browser.

diff --git a/site/docusaurus.config.js b/site/docusaurus.config.js
@@ -100,9 +100,14 @@ module.exports = {
           label: "Global APIs",
           position: "left",
           items: [
+            {
+              to: "global-guides",
+              activeBasePath: "global-guides",
+              label: "Guides",
+            },
             {
               to: "apis/global",
-              label: "Docs & API Reference",
+              label: "API Reference",
             },
           ],
         },
@@ -224,6 +229,16 @@ module.exports = {
         editUrl: "https://github.com/Bandwidth/api-docs/edit/main/site/",
       },
     ],
+    [
+      "@docusaurus/plugin-content-docs",
+      {
+        id: "global-guides",
+        path: "global-guides",
+        routeBasePath: "global-guides",
+        sidebarPath: require.resolve("./sidebarsGlobalGuides.js"),
+        editUrl: "https://github.com/Bandwidth/api-docs/edit/main/site/",
+      },
+    ],
     "docusaurus-plugin-sass",
   ],
 };
diff --git a/site/global-guides/intro.mdx b/site/global-guides/intro.mdx
@@ -0,0 +1,21 @@
+---
+id: global-guides
+title: Global Guides
+slug: /
+description: Bandwidth's Developer Docs
+sidebar_label: Introduction
+hide_table_of_contents: true
+keywords:
+  - bandwidth
+  - docs
+  - documentation
+  - api
+hide_title: false
+image: '@site/static/img/bw-icon.svg'
+---
+
+Bandwidth's Global APIs provide access to coverage in [60+ countries](https://www.bandwidth.com/coverage/). Learn more about Bandwidth's Products and APIs.
+
+| Guide | Description |
+|:------|:------------|
+| [Global In-App Calling](/global-guides/voice/guides/inAppCalling/) | How to use In-App Calling with the Global Network accessing the EMEA WebRTC Gateway. |
diff --git a/site/global-guides/voice/inAppGuide.mdx b/site/global-guides/voice/inAppGuide.mdx
@@ -0,0 +1,114 @@
+---
+id: inAppGuide
+title: How to use Global In-App Calling
+slug: /voice/guides/inAppCalling
+description: How to use Global In-App Calling (WebRTC)
+keywords:
+  - bandwidth
+  - voice
+hide_title: false
+image: '@site/static/img/bw-icon.svg'
+---
+
+In this guide we will show you how to use In-App Calling to place voice calls to web and mobile devices.
+
+Bandwidth offers an In-App Calling solution that allows our customers to use WebRTC voice capabilities present in web and mobile devices to place calls to critical destinations served by the Bandwidth voice network. This allows access to Bandwidth network services, quality and reach to advance any and all business needs surfaced by web browsers and mobile applications.
+
+The Bandwidth In-App Calling capability is designed for simplicity, reliability and voice quality; leveraging Bandwidth’s global voice network to deliver a voicepath that is managed from end to end.
+
+## Getting Started
+
+As Bandwidth operates two separate networks for US & Canada and Global please refer to the relevant guide based on your use case.
+
+### Global Network
+
+A Bandwidth WebRTC Gateway is deployed in the EMEA region. If your end-users are going to generate calls from the EMEA region we recommend using this gateway. Other regions can be used but may incur latency.
+
+Please ensure the following steps have been completed:
+
+- You have already created and set up your [Global Bandwidth](https://app.voxbone.com/home/#/) account.
+- You have contracted for In-App calling and your account has been enabled for this service. Please contact your account manager if you have not done this.
+
+### US & Canada Network
+
+A Bandwidth WebRTC Gateway deployed in the US is coming soon. Please contact your account manager for more information.
+
+## Overview
+
+Bandwidth In-App Calling is delivered by way of an SDK that is provided to the customer (that's you) to support development of your client experience. These Web and Mobile device SDKs enable the development of web and mobile applications that can negotiate with our Bandwidth WebRTC Gateway to establish voice calls into our network. The SDKs manage the initialization, call creation, call management, and call state change events that are needed to provide a comprehensive calling user experience.
+
+In addition to managing the relationship with the WebRTC Gateway, our Bandwidth capabilities are also used to secure the connection by granting tokens that will ensure that calls via the Gateway will be limited to (and billed to) your account.
+
+## How it Works
+
+![A high level overview of Bandwidth's In-App Calling](@site/static/img/docs-diagrams/voice/in-app-how.svg)
+
+## Specifying Call Routing
+
+### Caller ID (From)
+
+When placing a WebRTC call, the client must specify the **From** and **To** numbers. The **From** is the caller ID, a Bandwidth phone number, used to place an outbound call. 
+
+The Client SDK initiates a call into the WebRTC gateway, the **From** number generates an outbound call to the called destination, the **To** number which specifies the location. 
+
+**Note: The From number you use must be associated with your Bandwidth account.**
+
+- Depending on the Called Destination (To), we recommend using a local **From** number from the same country. This will ensure that costs are kept to a minimum for this leg of the call whether this is on-net or not.
+- On the Global Network, the **From** number must be activated for Outbound Calling.
+- You can use different **From** and/or **To** numbers to control the call routing logic.
+
+### Called Destination (To)
+
+The To is the destination of where you want the call to be routed to. This can either be:
++ A Bandwidth phone number
+    + Formatted in E164 format, the Voice URI on the number will control the logic of where the voice call is placed. This can be directly to your Contact Center via our BYOC for Genesys. On the Global network this will be defined as an on-net call and not incur any charges if terminated to a SIP endpoint.
++ A non-Bandwidth phone number
+    + Formatted in E164 format.
+
+### Buying Numbers
+
+The Bandwidth Global Portal is used for global coverage in 60+ countries. For more information on how to purchase numbers, see our [Buying Numbers](https://support.voxbone.com/hc/en-us/articles/360017105278-Buying-Numbers) support article.
+
+### Local Address Requirements
+
+Please refer to our [Guide to Compliance Support](https://support.voxbone.com/hc/en-us/articles/360017089718-A-Guide-to-Compliance-Support) to ensure Local Address Requirements are met for all numbers.
+
+## Security and Permissions
+
+In order to place calls into the Bandwidth Network (and of course be subject to billing for those calls) it is necessary to securely generate a Token that is associated with your account. That token is used by the web or mobile application user to indicate that the communications with the WebRTC gateway should be accepted by that gateway.
+
+### Generating credentials for an access token
+
+To generate an access token please contact your account manager and this will be provided to you. 
+
+Once you have received 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.
+:::
+
+As the token will be visible within your application we strongly advise to only use this scope. The token should be fetched from a server running in a secure environment, and provided to clients in a secure manner.
+
+We recommend regenerating the token every 30 seconds before expiry. It is not advisable to regenerate the token for every in-app voice call as this will create an unnecessary delay in the call being connected.
+
+Bandwidth accepts no responsibility for the loss of account credentials and any resulting network traffic, fraud, or undesired account access that results from failing to manage account access credentials in a completely secure manner. Minting of tokens is not included as a client SDK capability for the above reason.
+
+## Resources
+
+The following resources are available to aid in the development of quality solutions using Bandwidth In-App calling.
+
+### SDKs
+
+SDKs exposing all key capabilities are available in raw and packaged form.
+
+| Environment         | Package link                                                                            |
+| :------------------ | :-------------------------------------------------------------------------------------- |
+| Web / Javascript    | [bw-webrtc-sdk](https://www.npmjs.com/package/@bandwidth/bw-webrtc-sdk)                 |
+| Android / Kotlin    | Coming soon...                                                                          |
+| iOS / Swift         | Coming soon...                                                                          |
+
+### 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.
diff --git a/site/sidebarsGlobalGuides.js b/site/sidebarsGlobalGuides.js
@@ -0,0 +1,16 @@
+module.exports = {
+  mySidebar: [
+    {
+      type: "doc",
+      id: "global-guides",
+      label: "Introduction",
+    },
+    {
+      type: "category",
+      label: "Voice",
+      items: [
+        "voice/inAppGuide",
+      ]
+    }
+  ]
+};
diff --git a/site/static/img/docs-diagrams/voice/in-app-how.svg b/site/static/img/docs-diagrams/voice/in-app-how.svg