Glance Networks, Inc

Overview

The Glance NPM package is a react-based plugin that allows developers to create agent-side integrations into Glance. This package provides an interface that allows agents to join Glance Cobrowse, Mobile SDK, and Mobile Camera Share sessions in third-party platforms.

High-Level Overview

* Complete prerequisites
* Set up authentication to Glance
* Install the package and host it in a web application
* Enable Presence
* Enable Reporting

License

> See License file and for Glance terms of service.

$3

- Fix auth with saml login key
- Added BaseUrlEnvironment type

$3

- Updating it to correct cdn url

$3

- Bug fix for opening duplicate windows.

$3

-
=======

$3

- Adds support for the Glance UI Core Components, a collection of essential UI components for Glance applications.

$3

Enhancements

> * Mobile Camera Share button accessibility is controlled by the "Join sessions started by customers to show their cameras on mobile devices" Glance User privilege. The mobileCameraShare boolean property is no longer used for that and removed.
> * HistoricalReportingData interface export added
> * New autojoin boolean optional component property added with default value false
> * The list of possible glancebaseurl extended to cover different environments used during the release process
> * The errorMessage property added to provide ability to show errors
> * The reportingOrigin property added to provide ability to set a custom origin in the Glance Reporting (Activity Services API and/or Glance CRR)
> * The reportingExternalId property added to provide ability to set a custom xid in the Glance Reporting (Activity Services API and/or Glance CRR)
> * The uiVersion number property with allowed values 1 and 2 added to provide ability to switch between different UI versions of the component
> * The component was converted to be an ES Module and build switched to vite

Improvements and Fixes
>
> * The reportingCallback data structure changes and bug-fixes
> * The error handling/messaging for presence connect is enhanced
> * Documentation improvements

$3

> * You must have a Glance Admin account, and have access to your Glance API KEY.
>
> * You will need to setup an authentication URL. See Authentication section below.
>
> * Provision Glance Users - Each agent/app user has a Glance Account with a PUID set. Please see https://help.glance.net/account-management/manage_users/ for help managing users/puids.
>
> * A website tagged with Glance cobrowse or use the Glance cobrowse injector on a website.

Authentication

> Glance uses a form of authentication for external applications we call LoginKey . LoginKey's are temporary keys (think JWT) that allows access to Glance services from external platforms and are included in the request body when making a POST request. A requirement of using this package is to provide a URL that can be called to retrieve a loginkey for use by a user.
>
> Definitions:
>
> Glance Group - This a numerical value assigned by Glance for your enterprise or BU.
>
> PUID - Partner userid, this is a unique value per user, shared between Glance and a remote system. This value must be unique per user within a Glance group. This is often the user's SID or SSO account ID.
>
> Glance API Key - This can be found in your Glance admin section, it is secret and should NOT be used in any client-side code!
>
> When using this plugin, authentication is fully up to your system/scenario. Glance has provided some example code to get you started , yours can be written in any language you like, but upon successful authentication of the requesting user, your auth url should return a valid loginkey to be used with this component. A simple example of this is to wrap the code below in a simple "is the requesting user logged in" logic check, if true, return the loginkey, if not send 403 etc. You can verify your LoginKey result using the validator on this page
>
> You will need to setup a service such as a node express POST request
> to generate a Glance loginkey. The loginkey will give your agent
> access to the AgentJoin page for Cobrowse.
> Example Node Express.js POST Request:

``javascript
const express = require('express');
const app = express();

app.post('/loginkey', cors(corsOptions), (request, response) => {
try {
const version = 1;
const expires = (Math.round((new Date()).valueOf() / 1000)) + parseInt(environmentVariables.GLANCE_EXPIRATION, 10);
const keystring = environmentVariables.GLANCE_GROUP_ID + request.query.partneruserid + version + expires;
const CryptoJS = require('crypto-js');
const hmac = CryptoJS.HmacSHA256(keystring, environmentVariables.GLANCE_API_KEY);
const hmacb64 = hmac.toString(CryptoJS.enc.Base64);
const loginkey = "$" + version + "$" + expires + "$" + hmacb64.substr(0, 43).replace(/\+/g, '-').replace(/\//g, '_');

response.json({
'loginKey': loginkey,
'groupId': environmentVariables.GLANCE_GROUP_ID,
'expiration': expires
});

} catch(error) {
// handle error
}
});
`

> In the above example we have made GLANCE_GROUP_ID > GLANCE_EXPIRATION and GLANCE_API_KEY environment variables.

Install

`bash
npm i @glance-networks/agent-plugin
`

Usage

This is an example to get up and running, see the below table for additional props that can be added.

`typescript
import { Glance } from '@glance-networks/agent-plugin';
`

`tsx
groupid={GLANCE_GROUPID}
authurl={URL_TO_LOGINKEY}
puid={GLANCE_PUID}
openlocation={'tab' | 'window' | 'iframe' }
iframeid={IFRAME_ID}
gicon={true}
presence={true | false}
glancebaseurl={'beta' | 'production'}
visitorid={VISITOR_ID}
debugmode={true | false}
custominvoke={{
func: "customFunctionName",
args: {
dataParameter: "dataValue"
}
}}
/>
`

Properties

| Prop | Type | Description |
| ------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| authbody | function | Optional. If using authmethod=loginkey you can optionally pass data to your function via the POST request body. |
| authheaders | Object | Optional. If using authmethod=loginkey you can further customize your loginkey endpoint by passing headers to your function (e.g. Authorization header). |
| authmethod | enumeration | Optional. Default = loginkey. loginkey OR samlloginkey (requires you have set up SAML with Glance). |
| authurl | string | Required. Enter the URL to your login key service. |
| custominvoke | object | Optional. A Presence Agent can invoke Javascript functions defined on the Visitor's web page by providing an object that defines the following parameters: func name of the function, args function arguments. See below for more detail and an example. |
| debugmode | boolean | Optional. true turns on console logs to assist in debugging. false (default) turns off console logs. |
| gicon | boolean | Required. In order to show the Glance logo next to the Join button, set this to true. If gicon is not set, or it is set to false (default), then the logo will not appear. |
| glancebaseurl | string | Required. Should be production or beta if testing early release features on the glance beta platform. |
| groupid | integer | Required for loginkey, optional for samlloginkey. Enter your Glance Group ID (unique ID assigned to your company by Glance). |
| iframeid | string | Optional. The id of the iframe used when openlocation is set to iframe. If no id is given, a new iframe is created. |
| openlocation | string | tab (default) opens agent viewer in new tab.window opens agent viewer in new browser window. iframe opens agent viewer in an iframe. |
| openwindow | function | Optional. Use this to support the ability to open a Glance Cobrowse session in a new window or tab, when the URL is embedded in an Agent Desktop. |
| presence | boolean | Optional. Determines if presence is enabled. If undefined, presence is set to off. false (default) pressence is off, true presence is on. |
| presessionfunc | function | Optional. In case you need to do some work before a signaling the visitor to accept terms, you can pass a javascript function to this property. See below for more detail and an example. |
| puid | string | Required. Identifies the Glance user. |
| reportingCallback | function | Optional. Specify a function that will be called at the end of each cobrowse session to return session data. |
| visitorid | string | Required when pressence is set to true. Unique identifier that is used to track the visitor presence state and start the 1-click Cobrowse session. |
| errorMessage | string | Optional. Allows you to set error message text session. |
| reportingOrigin | string | Optional. Allows you to set origin property in the Glance Reporting. |
| reportingExternalId | string | Optional. Allows you to set xid property in the Glance Reporting. |
| uiVersion | number | Optional. Allows you to set uiVersion property for component. Allowed values are 1 (default) and 2. |

$3

`javascript
const exampleOpenWindowCallback = (url: string): void => {
// Opens a new window when a Glance Cobrowse session starts.
window.open(url, 'Glance', 'width=800,height=800');
};
`

$3

`javascript
authheaders={{
'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
'Authorization': 'Bearer ',
}}
authbody={
new URLSearchParams({
Token: ,
})
}
`

$3

> In order to allow for agent initiated sessions, Glance has created its Presence services framework. This service allows agents to "signal" visitor browsers to do things like start sessions, execute custom code, and so on. Each visitor is unqiuely identified within a Glance groupID using a unique vistor_id value. Visitors are "present" when they are actively focused on a browser tab that has Glance Cobrowse enabled and active or when focused inside a mobile app (Android/iOS SDK). An agent can click on the Join button when a visitor is present to initiate a session request to that user. This concept is usually invoked when an agent in the app/crm is contextually "looking" at a record such as an account/contact/lead etc. for that visitor and wants to cobrowse with that user.
>
> Definitions:
>
> * VisitorID - This is a unique value for the web visitor. This can be up to 62 digits in length, generally a hashed customer UUID format. This value is shared between the web property and the agent CRM for a given user.
>
> * Join Button - This is the UI component the Agent interacts with. It has a few states such as visitor present and not present. The button will be Blue when a visitor is not present currently, this allows teh agent to use the code methods to cnnect with a visitor/guest.
>
> The VISITOR_ID should be set dynamically as a prop to the React component based on a known value that is attached to a customer profile. Following React lifecycle methods, the UI state will update when a new value appears as the VISITOR_ID. You can set this property dynamically when an agent is viewing a record such as a case or contact record that is specific to a customer or action they are working on.
> The visitor side (browser) publishes a visitor_id, the agent side subscribes to that same string in order to determine if the user is available. More detail can be found here

$3

> Visitor's Page:

`javascript
GLANCE_COBROWSE.Custom = {
customFunctionName: function (params) {
// Do custom things on visitor's page.
}
}
`

> Agent's Glance Component:

`tsx
custominvoke={{
func: "customFunctionName",
args: {
dataParameter: "dataValue"
}
}}
/>
`

$3

Enable the ability to report on session metadata.

#### Example reportingCallback function

`javascript
reportingCallback={(data : HistoricalReportingData) => console.log(data)}
`

where HistoricalReportingData is

`typescript
export interface HistoricalReportingData {
sessionId: string; // the Glance Session Identifier to match with Customer Records Retriever, see https://help.glance.net/integrations/webservices/crr/
sessionStart: string; // the Glance Session start as ISO-8601 formatted string, YYYY-MM-DDTHH:mm:ss.sssZ
sessionEnd: string; // the Glance Session end as ISO-8601 formatted string, YYYY-MM-DDTHH:mm:ss.sssZ
duration: number; // the Glance Session time duration in seconds, between Glance Session end and start
}
`

#### Example of the reportingCallback data

`json
{
"sessionId": "111111111",
"sessionStart": "2023-08-14T17:36:02.000Z",
"sessionEnd": "2023-08-14T17:38:22.000Z",
"duration": 140
};
``

$3

You can pass a reference to a function into this prop if you want to handle some work
prior to signaling the visitor's page to show terms. For example, if you need to fetch some user information from
a database or generate a custom key to set on the visitor's session.

> Agent's Glance Component:

`tsx
presessionfunc={functionName}
/>
`

Changelog

$3

Enhancements

> * Adds ability to authenticate via SAML
> * Adds ability refresh loginkey after it expires
> * Adds user interface enhancements:
> * Improved user interface styling and error messages
> * Updated interface with new Glance logo
> * Adds the ability to end sessions from the agent interface

Improvements and Fixes

> * Improved Readme documentation
> * URL-Encoded credentials

$3

> * Adds Mobile Camera Share functionality, see Properties table for enabling this feature.
> * Improves event handling

$3

> * Adds ability to dynamically set a visitor id via the visitorid prop.

$3

> * Fixes a bug when using the authmethod and authurl props.
> * Fixes a bug when displaying presence state.

$3

> * Removes joinSession from presenceStartSession to allow for using a custom openViewer method, and to provide a custom callback for opening a tab/window.
> * Adds a behavior file to create the desired OnDetect behavior from presence events.
> * Modifies GCommon add eventlisteners method to only allow a single event to be added of each type.
> * Adds a state variable check in the presence behavior file to only listen for the presenceStartSession when no session has started.

$3

> * Added a reporting prop to specify a callback for reporting cobrowse data at the end of each session.

$3

> * Fixes package to remain in root directory

$3

> * Improves the Agent's presence experience by switching between states based on the visitorConnect event.
> * Adds optional authheaders and authbody props to further customize the loginkey authmetod service.

$3

> * Adds additional customization with a new prop openwindow to support the ability to open a Glance Cobrowse session in a new window or tab when the buttons are iframed in an Agent Desktop.

$3

> * Bug fix - prop glancebaseurl` was not optional.
> * Bug fix - changelog link in readme.md was broken.

$3

> * Updated Presence and Browser Agent Api scripts.
> * Improved the performance of the presence 1-Click Connect experience.
> * Refactor to use latest version of React 18.2.0.
> * Refactoring to separate components.
> * Minor bug fixes to improve the Cobrowse experience.

$3

> * Fixed a bug that prevented agents from entering a key into the join field.