Merge branch 'master' of github.com:wazo-platform/euc-plugins-js-sdk

.gitignore

@@ -1,2 +1,3 @@
 lib
 node_modules
+.vscode

documentation/docs/deeplink/deeplink.md

@@ -2,29 +2,54 @@
 displayed_sidebar: deeplinkSidebar
 ---
 
-# Deep Link
+# Deep Linking
 
-Deep linking is an app technology that enables direct navigation to specific in-app content or actions, enhancing user experience.
-It allows users to seamlessly access relevant app pages or features via links, improving engagement and user retention.
+Deep linking enables direct navigation to specific in-app content or actions, enhancing user experience. It allows users to seamlessly access relevant app pages or features via links, improving engagement and user retention.
 
 ## Web Application
 
-You can open the Web Application with a simple link, like [app.wazo.io](https://app.wazo.io).
+You now have the ability to control your Wazo application externally using URLs, the same way you would a regular website. If you're whitelabel-ling the application, you can use your own protocol.
 
-### Pre-filling the host name
+For instance, you can access:
+- the conference list with `https://app.wazo.io/phonebook/conferences`
+- the meetings page with `https://app.wazo.io/meetings`
+Navigate the web application in order to retrieve the URLs you'd like to link to from the location bar of your browser.
 
-By adding the parameter `host` in the Web Application link, the stack hostname will be pre-filled, like :  [app.wazo.io/?host=my-stack.io](https://app.wazo.io/?host=my-stack.io).
+### Pre-filling the host name
+By adding the `host` parameter to a Web Application link, the stack hostname will be pre-filled, like: `app.wazo.io/?host=my-stack.io`.
 
 ## Desktop Application
 
-You can open the Desktop Application with a deep link, like [wazo://](wazo://).
+You can also control Wazo Desktop in a similar fashion.
+
+Instead of using `https://app.wazo.io`, you may use the `wazo://` protocol.
+
+For instance, you can access:
+- the conference list with `wazo://phonebook/conferences`
+- the meetings page with `wazo://meetings`
+On your first attempt, you will be prompted to allow access to the application.
 
-If you're whitelabel-ling the application, you can use your own protocol.
+Following your approval, you will land on the page directly.
 
 ### Pre-filling the host name
+By adding the `host` parameter to the Desktop Application link, the stack hostname will be pre-filled, like: `wazo://?host=my-stack.io`.
+
+## Initiating a call
+
+You can also use URLs to initiate a call with the `[protocol]:/calls/[your-number]` URL structure.
+
+For instance:
+- `https://app.wazo.io/calls/418-555-1234` loads the web application and redirects you to the lobby, from which you can proceed with the call.
+- `wazo://calls/418-555-1234`
+will bring the desktop app to the foreground and achieve the same result.
 
-By adding the parameter `host` in the Desktop Application link, the stack hostname will be pre-filled, like : [wazo://?host=my-stack.io](wazo://?host=my-stack.io).
+### Bypassing the lobby
+You can bypass the lobby and proceed directly with the call by adding the `direct` query string:
 
-## Mobile Application
+- `https://app.wazo.io/calls/418-555-1234?direct`
+- `wazo://calls/418-555-1234?direct`
+The `tel:`, `call:` and `callto:` protocols automatically bypass the lobby:
 
-The Mobile Application uses the same link as the Desktop Application.
+- `tel:418-555-1234`
+- `call:418-555-1234`
+- `callto:418-555-1234` (not implemented yet)

documentation/docs/plugins/sdk.md

@@ -62,7 +62,7 @@ It's at this moment the magic happens, add your own logic inside our products. D
 
 When a plugin is unloaded because of a user action (ex: logout), this listener `app.onPluginUnLoaded()` will be called. Other listeners will be disabled when unloaded. To prevent side effects, it's important to remove any watcher added in the initializing phase.
 
-When the user logs in again, the `backgroundScript` will be loaded again, please make sure to release everything in `onPluginUnLoaded`. 
+When the user logs in again, the `backgroundScript` will be reloaded, please make sure to release everything in `onPluginUnLoaded`.
 
 :::info
 If you're using a **background script**, it's important to close any WebSocket or listeners at this cycle of the plugin.
@@ -267,12 +267,17 @@ app.resetNavBarColor();
 We can display a modal in the `backgroundScript` with:
 
 ```js
-app.displayModal({ url, title, text, htmlText, height, width });
+app.displayModal({ url, title, text, htmlText, height, width, hideCloseButton });
 ```
 
 If `url` is present, the modal will display an iframe with the content of the url.
 If `htmlText` is present, the modal will display this text in a html contact, otherwise the `text` attribute will be used.
 The `height` and `width` accept valid CSS values, like `500px` or `80%`.
+`hideCloseButton` (default to false) determines if the close button should be displayed, or if the user should handle closing of the modal in the html content (through `app.removeModal()` method).
+
+:::note
+On mobile, links with a `target="_blank"` attribute will be opened in the user's default browser.
+:::
 
 Example:
 
@@ -292,6 +297,29 @@ app.onCallIncoming = async call => {
 };
 ```
 
+#### Displaying a banner (mobile only)
+
+We can display a banner in the `backgroundScript` with:
+
+```js
+app.displayBanner({ url, height, width, hideCloseButton });
+```
+
+If `url` is present, the modal will display an iframe with the content of the url.
+The `height` accepts valid CSS values, like `500px` or `80%`.
+The `width` accepts valid CSS values, like `500px` or `80%`, used on WDA (min: `300px`).
+`hideCloseButton` (default to false) determines if the close button should be displayed, or if the user should handle closing of the modal in the html content (through `app.removeModal()` method).
+
+We can then call `app.removeBanner()` in the `backgroundScript` or the loaded content.
+
+:::note
+On mobile, links with a `target="_blank"` attribute will be opened in the user's default browser.
+:::
+
+:::note
+On WDA, the banner will be integrated with other banners like incoming calls. Other banners will be displayed below.
+:::
+
 #### Checking if a call has a local video stream
 
 ```js

documentation/docs/plugins/wda-examples.md

@@ -69,6 +69,46 @@ await app.initialize();
     source="https://github.com/wazo-communication/euc-plugins-js-sdk/tree/master/documentation/static/examples/wda/incoming-call-modal"
 />
 
+## Displaying a banner
+
+```mdx-code-block
+<BrowserWindow url="https://app.wazo.io">
+```
+![Banner](/img/app-example-banner.png)
+```mdx-code-block
+</BrowserWindow>
+```
+
+```js
+// backgroundScript
+await app.initialize();
+app.displayBanner({
+  url: 'https://grim.ngrok.io/banner.html',
+  height: '60px',
+  hideCloseButton: true,
+});
+
+```
+
+In the `banner.html` file:
+```html
+<html>
+  <body>
+      <a href="https://my-website.com" target="_blank">You trial has expired</a>
+      <a href="#" id="close">x</a>
+
+      <script type="module">
+        app.initialize();
+
+        document.getElementById('close').addEventListener('click', (e) => {
+          e.preventDefault();
+          app.removeBanner();
+        });
+      </script>
+  </body>
+</html>
+```
+
 ## Send and receive messages between background script and tabs
 
 ```mdx-code-block

documentation/docusaurus.config.js

@@ -89,7 +89,7 @@ const config = {
             type: 'doc',
             docId: 'deeplink/deeplink',
             position: 'left',
-            label: 'Deeplink',
+            label: 'Deep Linking',
             activeBaseRegex: '/deeplink/'
           },
 

documentation/sidebars.js

@@ -140,7 +140,7 @@ const sidebars = {
     {
       type: 'ref',
       id: 'deeplink/deeplink',
-      label: 'Deeplink'
+      label: 'Deep Linking'
     },
   ],
 };

src/app.ts

@@ -13,6 +13,7 @@ import {
   WDASession,
   PortalSession,
   UpdateBadgeArgs,
+  DisplayBannerArgs,
   MobileMenuItem,
 } from './types.js';
 
@@ -69,10 +70,13 @@ import {
   EVENT_MOBILE_SHOW_BOTTOM_NAV,
   EVENT_MOBILE_ON_MENU_ACTION,
   EVENT_MOBILE_ON_HEADER_BACK,
+  EVENT_DISPLAY_BANNER,
+  EVENT_REMOVE_BANNER,
 } from './constants.js';
 
 declare global {
-  // Deprecated, use `_configurePlugin` instead
+  // Used for mobile
+  var pluginId: string;
   var _setPluginId: Function;
   var _configurePlugin: Function;
   var Wazo: any;
@@ -130,7 +134,7 @@ export class App {
     this._initializeCompleted = false;
     this._initializeResolve = null;
     this._initializeTimeout = null;
-    this._pluginId = null;
+    this._pluginId = globalThis?.pluginId || null;
     this._baseUrl = null;
     this._entityId = null;
     this._isBackground = !window.name;
@@ -165,7 +169,8 @@ export class App {
       }
     }
 
-    // deprecated: Used in background script, we expose a global method to be used in the <script> tag directly after importing the backgroundScript url
+    // We expose a global method to be used in the <script> tag directly after importing the `backgroundScript` url
+    // Also used in mobile
     globalThis._setPluginId = this._setPluginId;
     globalThis._configurePlugin = this._configurePlugin;
   }
@@ -252,8 +257,8 @@ export class App {
 
   displayNotification = (title: string, text: string) => this._sendMessage(EVENT_DISPLAY_NOTIFICATION, { title, text });
 
-  displayModal = ({ url, title, text, htmlText, height, width }: ModalParameter) =>
-    this._sendMessage(EVENT_DISPLAY_MODAL, { url, title, text, htmlText, height, width });
+  displayModal = ({ url, title, text, htmlText, height, width, hideCloseButton }: ModalParameter) =>
+    this._sendMessage(EVENT_DISPLAY_MODAL, { url, title, text, htmlText, height, width, hideCloseButton });
 
   removeModal = () => this._sendMessage(EVENT_REMOVE_MODAL);
 
@@ -267,6 +272,10 @@ export class App {
 
   updateBadge = (args: UpdateBadgeArgs) => this._sendMessage(EVENT_UPDATE_BADGE, { ...args, entityId: args.entityId || this._entityId || 'update-badge-null-entity-id' });
 
+  displayBanner = (args: DisplayBannerArgs) => this._sendMessage(EVENT_DISPLAY_BANNER, { ...args, entityId: this._entityId || 'display-banner-null-entity-id' });
+
+  closeBanner = () => this._sendMessage(EVENT_REMOVE_BANNER, { entityId: this._entityId || 'remove-banner-null-entity-id' });
+
   // Portal
   changeToolbarDisplay = (display: boolean) => this._sendMessage(EVENT_CHANGE_TOOLBAR_DISPLAY, { display });
 

src/constants.ts

@@ -45,6 +45,9 @@ export const EVENT_PARTICIPANT_LEAVE_ROOM = 'wazo/EVENT_PARTICIPANT_LEAVE_ROOM';
 export const EVENT_IGNORE_CALL = 'wazo/EVENT_IGNORE_CALL';
 export const EVENT_ON_NEW_SESSION = 'wazo/EVENT_ON_NEW_SESSION';
 export const EVENT_UPDATE_BADGE = 'wazo/EVENT_UPDATE_BADGE';
+export const EVENT_DISPLAY_BANNER = 'wazo/EVENT_DISPLAY_BANNER';
+export const EVENT_REMOVE_BANNER = 'wazo/EVENT_REMOVE_BANNER';
+
 
 // Portal
 export const EVENT_ON_CONNECTED_TO_STACK = 'wazo/EVENT_ON_CONNECTED_TO_STACK';

src/types.ts

@@ -203,6 +203,7 @@ export interface ModalParameter {
   htmlText?: string;
   height?: string|number;
   width?: string|number;
+  hideCloseButton?: boolean;
 }
 
 export interface IframeCss { [index: string]: string|number }
@@ -257,6 +258,11 @@ export type UpdateBadgeArgs = {
   anchorOrigin?: { horizontal: 'left' | 'right', vertical: 'top' | 'bottom' }
 };
 
+export type DisplayBannerArgs = {
+  url?: string,
+  height: number,
+};
+
 export type MobileMenuItem = {
   label: string,
   id: string,