@webex/internal-plugin-metrics 3.3.1-next.5 → 3.3.1-next.7

package/dist/types/metrics.types.d.ts

@@ -7,6 +7,9 @@ export type EnvironmentType = NonNullable<RawEvent['origin']['environment']>;
 export type NewEnvironmentType = NonNullable<RawEvent['origin']['newEnvironment']>;
 export type ClientLaunchMethodType = NonNullable<RawEvent['origin']['clientInfo']>['clientLaunchMethod'];
 export type BrowserLaunchMethodType = NonNullable<RawEvent['origin']['clientInfo']>['browserLaunchMethod'];
+export type MetricEventProduct = 'webex' | 'wxcc_desktop';
+export type MetricEventAgent = 'user' | 'browser' | 'system' | 'sdk' | 'redux' | 'service';
+export type MetricEventVerb = 'create' | 'get' | 'fetch' | 'update' | 'list' | 'delete' | 'select' | 'view' | 'set' | 'toggle' | 'load' | 'reload' | 'click' | 'hover' | 'register' | 'unregister' | 'enable' | 'disable' | 'use' | 'complete' | 'submit' | 'apply' | 'cancel' | 'abort' | 'sync' | 'login' | 'logout';
 export type SubmitClientEventOptions = {
     meetingId?: string;
     mediaConnections?: any[];
@@ -37,11 +40,27 @@ export interface ClientEvent {
     payload?: RawClientEvent;
     options?: SubmitClientEventOptions;
 }
+export interface BehavioralEventContext {
+    app: {
+        version: string;
+    };
+    device: {
+        id: string;
+    };
+    locale: string;
+    os: {
+        name: string;
+        version: string;
+    };
+}
 export interface BehavioralEvent {
-    name: 'host.meeting.participant.admitted' | 'sdk.media-flow.started';
-    payload?: never;
-    options?: never;
+    context: BehavioralEventContext;
+    metricName: string;
+    tags: Record<string, string | number | boolean>;
+    timestamp: number;
+    type: string[];
 }
+export type BehavioralEventPayload = BehavioralEvent['tags'];
 export interface OperationalEvent {
     name: never;
     payload?: never;
@@ -60,7 +79,7 @@ export interface MediaQualityEvent {
 export type RecursivePartial<T> = {
     [P in keyof T]?: T[P] extends (infer U)[] ? RecursivePartial<U>[] : T[P] extends object ? RecursivePartial<T[P]> : T[P];
 };
-export type MetricEventNames = InternalEvent['name'] | ClientEvent['name'] | BehavioralEvent['name'] | OperationalEvent['name'] | FeatureEvent['name'] | MediaQualityEvent['name'];
+export type MetricEventNames = InternalEvent['name'] | ClientEvent['name'] | BehavioralEvent['metricName'] | OperationalEvent['name'] | FeatureEvent['name'] | MediaQualityEvent['name'];
 export type ClientInfo = NonNullable<RawEvent['origin']['clientInfo']>;
 export type ClientType = NonNullable<RawEvent['origin']['clientInfo']>['clientType'];
 export type SubClientType = NonNullable<RawEvent['origin']['clientInfo']>['subClientType'];
@@ -80,9 +99,11 @@ export type SubmitInternalEvent = (args: {
     options?: any;
 }) => void;
 export type SubmitBehavioralEvent = (args: {
-    name: BehavioralEvent['name'];
-    payload?: RecursivePartial<BehavioralEvent['payload']>;
-    options?: any;
+    product: MetricEventProduct;
+    agent: MetricEventAgent;
+    target: string;
+    verb: MetricEventVerb;
+    payload?: BehavioralEventPayload;
 }) => void;
 export type SubmitClientEvent = (args: {
     name: ClientEvent['name'];

package/dist/types/new-metrics.d.ts

@@ -1,6 +1,7 @@
 import { WebexPlugin } from '@webex/webex-core';
 import CallDiagnosticMetrics from './call-diagnostic/call-diagnostic-metrics';
-import { RecursivePartial, ClientEvent, FeatureEvent, BehavioralEvent, OperationalEvent, MediaQualityEvent, InternalEvent, SubmitClientEventOptions } from './metrics.types';
+import BehavioralMetrics from './behavioral/behavioral-metrics';
+import { RecursivePartial, MetricEventProduct, MetricEventAgent, MetricEventVerb, ClientEvent, FeatureEvent, BehavioralEventPayload, OperationalEvent, MediaQualityEvent, InternalEvent, SubmitClientEventOptions } from './metrics.types';
 import CallDiagnosticLatencies from './call-diagnostic/call-diagnostic-metrics-latencies';
 /**
  * Metrics plugin to centralize all types of metrics.
@@ -10,6 +11,7 @@ declare class Metrics extends WebexPlugin {
     static instance: Metrics;
     callDiagnosticLatencies: CallDiagnosticLatencies;
     callDiagnosticMetrics: CallDiagnosticMetrics;
+    behavioralMetrics: BehavioralMetrics;
     /**
      * Constructor
      * @param args
@@ -31,15 +33,21 @@ declare class Metrics extends WebexPlugin {
         payload?: RecursivePartial<InternalEvent['payload']>;
         options?: any;
     }): void;
+    /**
+     * @returns true once we have the deviceId we need to submit behavioral events to Amplitude
+     */
+    isReadyToSubmitBehavioralEvents(): boolean;
     /**
      * Behavioral event
      * @param args
      */
-    submitBehavioralEvent({ name, payload, options, }: {
-        name: BehavioralEvent['name'];
-        payload?: RecursivePartial<BehavioralEvent['payload']>;
-        options?: any;
-    }): void;
+    submitBehavioralEvent({ product, agent, target, verb, payload, }: {
+        product: MetricEventProduct;
+        agent: MetricEventAgent;
+        target: string;
+        verb: MetricEventVerb;
+        payload?: BehavioralEventPayload;
+    }): any;
     /**
      * Operational event
      * @param args

package/package.json

@@ -26,22 +26,22 @@
     "@webex/eslint-config-legacy": "0.0.0",
     "@webex/jest-config-legacy": "0.0.0",
     "@webex/legacy-tools": "0.0.0",
-    "@webex/test-helper-chai": "3.3.1-next.5",
-    "@webex/test-helper-mocha": "3.3.1-next.5",
-    "@webex/test-helper-mock-webex": "3.3.1-next.5",
-    "@webex/test-helper-test-users": "3.3.1-next.5",
+    "@webex/test-helper-chai": "3.3.1-next.7",
+    "@webex/test-helper-mocha": "3.3.1-next.7",
+    "@webex/test-helper-mock-webex": "3.3.1-next.7",
+    "@webex/test-helper-test-users": "3.3.1-next.7",
     "eslint": "^8.24.0",
     "prettier": "^2.7.1",
     "sinon": "^9.2.4"
   },
   "dependencies": {
-    "@webex/common": "3.3.1-next.5",
-    "@webex/common-timers": "3.3.1-next.5",
+    "@webex/common": "3.3.1-next.7",
+    "@webex/common-timers": "3.3.1-next.7",
     "@webex/event-dictionary-ts": "^1.0.1406",
-    "@webex/internal-plugin-metrics": "3.3.1-next.5",
-    "@webex/test-helper-chai": "3.3.1-next.5",
-    "@webex/test-helper-mock-webex": "3.3.1-next.5",
-    "@webex/webex-core": "3.3.1-next.5",
+    "@webex/internal-plugin-metrics": "3.3.1-next.7",
+    "@webex/test-helper-chai": "3.3.1-next.7",
+    "@webex/test-helper-mock-webex": "3.3.1-next.7",
+    "@webex/webex-core": "3.3.1-next.7",
     "ip-anonymize": "^0.1.0",
     "lodash": "^4.17.21",
     "uuid": "^3.3.2"
@@ -54,5 +54,5 @@
     "test:style": "eslint ./src/**/*.*",
     "test:unit": "webex-legacy-tools test --unit --runner mocha"
   },
-  "version": "3.3.1-next.5"
+  "version": "3.3.1-next.7"
 }

package/src/behavioral/behavioral-metrics.ts

@@ -0,0 +1,179 @@
+import {merge} from 'lodash';
+import {BrowserDetection} from '@webex/common';
+import {StatelessWebexPlugin} from '@webex/webex-core';
+import {getOSNameInternal} from '../metrics';
+import {BEHAVIORAL_LOG_IDENTIFIER} from './config';
+import {
+  MetricEventProduct,
+  MetricEventAgent,
+  MetricEventVerb,
+  BehavioralEventContext,
+  BehavioralEvent,
+  BehavioralEventPayload,
+} from '../metrics.types';
+import ClientMetricsBatcher from '../client-metrics-batcher';
+
+const {getOSVersion, getBrowserName, getBrowserVersion} = BrowserDetection();
+
+/**
+ * @description Util class to handle Behavioral Metrics
+ * @export
+ * @class BehavioralMetrics
+ */
+export default class BehavioralMetrics extends StatelessWebexPlugin {
+  // @ts-ignore
+  private clientMetricsBatcher: ClientMetricsBatcher;
+  private logger: any; // to avoid adding @ts-ignore everywhere
+  private device: any;
+  private version: string;
+
+  /**
+   * Constructor
+   * @param {any[]} args
+   */
+  constructor(...args) {
+    super(...args);
+    // @ts-ignore
+    this.logger = this.webex.logger;
+    // @ts-ignore
+    this.device = this.webex.internal.device;
+    // @ts-ignore
+    this.version = this.webex.version;
+    // @ts-ignore
+    this.clientMetricsBatcher = new ClientMetricsBatcher({}, {parent: this.webex});
+  }
+
+  /**
+   * Returns the deviceId from our registration with WDM.
+   * @returns {string} deviceId or empty string
+   */
+  private getDeviceId(): string {
+    const {url} = this.device;
+    if (url && url.length !== 0) {
+      const n = url.lastIndexOf('/');
+      if (n !== -1) {
+        return url.substring(n + 1);
+      }
+    }
+
+    return '';
+  }
+
+  /**
+   * Returns the context object to be submitted with all behavioral metrics.
+   * @returns {BehavioralEventContext}
+   */
+  private getContext(): BehavioralEventContext {
+    const context: BehavioralEventContext = {
+      app: {
+        version: this.version,
+      },
+      device: {
+        id: this.getDeviceId(),
+      },
+      locale: window.navigator.language,
+      os: {
+        name: getOSNameInternal(),
+        version: getOSVersion(),
+      },
+    };
+
+    return context;
+  }
+
+  /**
+   * Returns the default tags to be included with all behavioral metrics.
+   * @returns {BehavioralEventPayload}
+   */
+  private getDefaultTags(): BehavioralEventPayload {
+    const tags = {
+      browser: getBrowserName(),
+      browserHeight: window.innerHeight,
+      browserVersion: getBrowserVersion(),
+      browserWidth: window.innerWidth,
+      domain: window.location.hostname,
+      inIframe: window.self !== window.top,
+      locale: window.navigator.language,
+      os: getOSNameInternal(),
+    };
+
+    return tags;
+  }
+
+  /**
+   * Creates the object to send to our metrics endpoint for a behavioral event
+   * @param {MetricEventProduct} product
+   * @param {MetricEventAgent} agent
+   * @param {string} target
+   * @param {MetricEventVerb} verb
+   * @returns {BehavioralEventPayload}
+   */
+  private createEventObject({
+    product,
+    agent,
+    target,
+    verb,
+    payload,
+  }: {
+    product: MetricEventProduct;
+    agent: MetricEventAgent;
+    target: string;
+    verb: MetricEventVerb;
+    payload?: BehavioralEventPayload;
+  }): BehavioralEvent {
+    const metricName = `${product}.${agent}.${target}.${verb}`;
+    let allTags: BehavioralEventPayload = payload;
+    allTags = merge(allTags, this.getDefaultTags());
+
+    const event: BehavioralEvent = {
+      context: this.getContext(),
+      metricName,
+      tags: allTags,
+      timestamp: Date.now(),
+      type: ['behavioral'],
+    };
+
+    return event;
+  }
+
+  /**
+   * Returns true once we're ready to submit behavioral metrics, after startup.
+   * @returns {boolean} true when deviceId is defined and non-empty
+   */
+  public isReadyToSubmitBehavioralEvents(): boolean {
+    const deviceId = this.getDeviceId();
+
+    return deviceId && deviceId.length !== 0;
+  }
+
+  /**
+   * Submit a behavioral metric to our metrics endpoint.
+   * @param {MetricEventProduct} product the product from which the metric is being submitted, e.g. 'webex' web client, 'wxcc_desktop'
+   * @param {MetricEventAgent} agent the source of the action for this metric
+   * @param {string} target the 'thing' that this metric includes information about
+   * @param {MetricEventVerb} verb the action that this metric includes information about
+   * @param {BehavioralEventPayload} payload information specific to this event. This should be flat, i.e. it should not include nested objects.
+   * @returns {Promise<any>}
+   */
+  public submitBehavioralEvent({
+    product,
+    agent,
+    target,
+    verb,
+    payload,
+  }: {
+    product: MetricEventProduct;
+    agent: MetricEventAgent;
+    target: string;
+    verb: MetricEventVerb;
+    payload?: BehavioralEventPayload;
+  }) {
+    this.logger.log(
+      BEHAVIORAL_LOG_IDENTIFIER,
+      `BehavioralMetrics: @submitBehavioralEvent. Submit Behavioral event: ${product}.${agent}.${target}.${verb}`
+    );
+    const behavioralEvent = this.createEventObject({product, agent, target, verb, payload});
+
+    return this.clientMetricsBatcher.request(behavioralEvent);
+  }
+}

package/src/behavioral/config.ts

@@ -0,0 +1,3 @@
+/* eslint-disable import/prefer-default-export */
+
+export const BEHAVIORAL_LOG_IDENTIFIER = 'behavioral-events -> ';

package/src/call-diagnostic/call-diagnostic-metrics.util.ts

@@ -21,6 +21,7 @@ import {
   MISSING_ROAP_ANSWER_CLIENT_CODE,
   WBX_APP_API_URL,
   ERROR_DESCRIPTIONS,
+  ICE_AND_REACHABILITY_FAILED_CLIENT_CODE,
 } from './config';
 
 const {getOSName, getOSVersion, getBrowserName, getBrowserVersion} = BrowserDetection();
@@ -371,10 +372,12 @@ export const generateClientErrorCodeForIceFailure = ({
   signalingState,
   iceConnected,
   turnServerUsed,
+  unreachable,
 }: {
   signalingState: RTCPeerConnection['signalingState'];
   iceConnected: boolean;
   turnServerUsed: boolean;
+  unreachable: boolean;
 }) => {
   let errorCode = ICE_FAILURE_CLIENT_CODE; // default;
 
@@ -388,7 +391,11 @@ export const generateClientErrorCodeForIceFailure = ({
 
   if (signalingState !== 'have-local-offer' && !iceConnected) {
     if (turnServerUsed) {
-      errorCode = ICE_FAILED_WITH_TURN_TLS_CLIENT_CODE;
+      if (unreachable) {
+        errorCode = ICE_AND_REACHABILITY_FAILED_CLIENT_CODE;
+      } else {
+        errorCode = ICE_FAILED_WITH_TURN_TLS_CLIENT_CODE;
+      }
     } else {
       errorCode = ICE_FAILED_WITHOUT_TURN_TLS_CLIENT_CODE;
     }

package/src/call-diagnostic/config.ts

@@ -16,6 +16,7 @@ export const MISSING_ROAP_ANSWER_CLIENT_CODE = 2007;
 export const DTLS_HANDSHAKE_FAILED_CLIENT_CODE = 2008;
 export const ICE_FAILED_WITH_TURN_TLS_CLIENT_CODE = 2010;
 export const ICE_FAILED_WITHOUT_TURN_TLS_CLIENT_CODE = 2009;
+export const ICE_AND_REACHABILITY_FAILED_CLIENT_CODE = 2011;
 export const WBX_APP_API_URL = 'wbxappapi'; // MeetingInfo WebexAppApi response object normally contains a body.url that includes the string 'wbxappapi'
 
 export const WEBEX_SUB_SERVICE_TYPES: Record<string, ClientSubServiceType> = {
@@ -125,6 +126,7 @@ export const ERROR_DESCRIPTIONS = {
   DTLS_HANDSHAKE_FAILED: 'DTLSHandshakeFailed',
   ICE_FAILED_WITHOUT_TURN_TLS: 'ICEFailedWithoutTURN_TLS',
   ICE_FAILED_WITH_TURN_TLS: 'ICEFailedWithTURN_TLS',
+  ICE_AND_REACHABILITY_FAILED: 'ICEAndReachabilityFailed',
   SDP_OFFER_CREATION_ERROR: 'SdpOfferCreationError',
   SDP_OFFER_CREATION_ERROR_MISSING_CODEC: 'SdpOfferCreationErrorMissingCodec',
 };
@@ -392,6 +394,11 @@ export const CLIENT_ERROR_CODE_TO_ERROR_PAYLOAD: Record<number, Partial<ClientEv
   },
   [ICE_FAILED_WITH_TURN_TLS_CLIENT_CODE]: {
     errorDescription: ERROR_DESCRIPTIONS.ICE_FAILED_WITH_TURN_TLS,
+    category: 'media',
+    fatal: true,
+  },
+  [ICE_AND_REACHABILITY_FAILED_CLIENT_CODE]: {
+    errorDescription: ERROR_DESCRIPTIONS.ICE_AND_REACHABILITY_FAILED,
     category: 'network',
     fatal: true,
   },

package/src/index.ts

@@ -22,6 +22,7 @@ import * as CALL_DIAGNOSTIC_CONFIG from './call-diagnostic/config';
 import * as CallDiagnosticUtils from './call-diagnostic/call-diagnostic-metrics.util';
 import CallDiagnosticMetrics from './call-diagnostic/call-diagnostic-metrics';
 import CallDiagnosticLatencies from './call-diagnostic/call-diagnostic-metrics-latencies';
+import BehavioralMetrics from './behavioral/behavioral-metrics';
 
 registerInternalPlugin('metrics', Metrics, {
   config,
@@ -41,6 +42,7 @@ export {
   CallDiagnosticUtils,
   CallDiagnosticLatencies,
   CallDiagnosticMetrics,
+  BehavioralMetrics,
 };
 export type {
   ClientEvent,

package/src/metrics.types.ts

@@ -20,6 +20,39 @@ export type BrowserLaunchMethodType = NonNullable<
   RawEvent['origin']['clientInfo']
 >['browserLaunchMethod'];
 
+export type MetricEventProduct = 'webex' | 'wxcc_desktop';
+
+export type MetricEventAgent = 'user' | 'browser' | 'system' | 'sdk' | 'redux' | 'service';
+
+export type MetricEventVerb =
+  | 'create'
+  | 'get'
+  | 'fetch'
+  | 'update'
+  | 'list'
+  | 'delete'
+  | 'select'
+  | 'view'
+  | 'set'
+  | 'toggle'
+  | 'load'
+  | 'reload'
+  | 'click'
+  | 'hover'
+  | 'register'
+  | 'unregister'
+  | 'enable'
+  | 'disable'
+  | 'use'
+  | 'complete'
+  | 'submit'
+  | 'apply'
+  | 'cancel'
+  | 'abort'
+  | 'sync'
+  | 'login'
+  | 'logout';
+
 export type SubmitClientEventOptions = {
   meetingId?: string;
   mediaConnections?: any[];
@@ -66,13 +99,26 @@ export interface ClientEvent {
   options?: SubmitClientEventOptions;
 }
 
+export interface BehavioralEventContext {
+  app: {version: string};
+  device: {id: string};
+  locale: string;
+  os: {
+    name: string;
+    version: string;
+  };
+}
+
 export interface BehavioralEvent {
-  // TODO: not implemented
-  name: 'host.meeting.participant.admitted' | 'sdk.media-flow.started';
-  payload?: never;
-  options?: never;
+  context: BehavioralEventContext;
+  metricName: string;
+  tags: Record<string, string | number | boolean>;
+  timestamp: number;
+  type: string[];
 }
 
+export type BehavioralEventPayload = BehavioralEvent['tags'];
+
 export interface OperationalEvent {
   // TODO: not implemented
   name: never;
@@ -104,7 +150,7 @@ export type RecursivePartial<T> = {
 export type MetricEventNames =
   | InternalEvent['name']
   | ClientEvent['name']
-  | BehavioralEvent['name']
+  | BehavioralEvent['metricName']
   | OperationalEvent['name']
   | FeatureEvent['name']
   | MediaQualityEvent['name'];
@@ -137,9 +183,11 @@ export type SubmitInternalEvent = (args: {
 }) => void;
 
 export type SubmitBehavioralEvent = (args: {
-  name: BehavioralEvent['name'];
-  payload?: RecursivePartial<BehavioralEvent['payload']>;
-  options?: any;
+  product: MetricEventProduct;
+  agent: MetricEventAgent;
+  target: string;
+  verb: MetricEventVerb;
+  payload?: BehavioralEventPayload;
 }) => void;
 
 export type SubmitClientEvent = (args: {

package/src/new-metrics.ts

@@ -6,11 +6,15 @@
 import {WebexPlugin} from '@webex/webex-core';
 
 import CallDiagnosticMetrics from './call-diagnostic/call-diagnostic-metrics';
+import BehavioralMetrics from './behavioral/behavioral-metrics';
 import {
   RecursivePartial,
+  MetricEventProduct,
+  MetricEventAgent,
+  MetricEventVerb,
   ClientEvent,
   FeatureEvent,
-  BehavioralEvent,
+  BehavioralEventPayload,
   OperationalEvent,
   MediaQualityEvent,
   InternalEvent,
@@ -32,6 +36,7 @@ class Metrics extends WebexPlugin {
   callDiagnosticLatencies: CallDiagnosticLatencies;
   // Helper classes to handle the different types of metrics
   callDiagnosticMetrics: CallDiagnosticMetrics;
+  behavioralMetrics: BehavioralMetrics;
 
   /**
    * Constructor
@@ -56,6 +61,8 @@ class Metrics extends WebexPlugin {
     this.webex.once('ready', () => {
       // @ts-ignore
       this.callDiagnosticMetrics = new CallDiagnosticMetrics({}, {parent: this.webex});
+      // @ts-ignore
+      this.behavioralMetrics = new BehavioralMetrics({}, {parent: this.webex});
     });
   }
 
@@ -79,21 +86,40 @@ class Metrics extends WebexPlugin {
     }
   }
 
+  /**
+   * @returns true once we have the deviceId we need to submit behavioral events to Amplitude
+   */
+  isReadyToSubmitBehavioralEvents() {
+    return this.behavioralMetrics.isReadyToSubmitBehavioralEvents();
+  }
+
   /**
    * Behavioral event
    * @param args
    */
   submitBehavioralEvent({
-    name,
+    product,
+    agent,
+    target,
+    verb,
     payload,
-    options,
   }: {
-    name: BehavioralEvent['name'];
-    payload?: RecursivePartial<BehavioralEvent['payload']>;
-    options?: any;
+    product: MetricEventProduct;
+    agent: MetricEventAgent;
+    target: string;
+    verb: MetricEventVerb;
+    payload?: BehavioralEventPayload;
   }) {
-    this.callDiagnosticLatencies.saveTimestamp({key: name});
-    throw new Error('Not implemented.');
+    if (!this.behavioralMetrics) {
+      // @ts-ignore
+      this.webex.logger.log(
+        `NewMetrics: @submitBehavioralEvent. Attempted to submit before webex.ready: ${product}.${agent}.${target}.${verb}`
+      );
+
+      return Promise.resolve();
+    }
+
+    return this.behavioralMetrics.submitBehavioralEvent({product, agent, target, verb, payload});
   }
 
   /**