@zohodesk/i18n 1.0.0-beta.34 → 1.0.0-beta.36-murphy

package/docs/murphy/04-MURPHY_FRONTEND_INIT.md

@@ -0,0 +1,437 @@
+# Murphy Frontend Initialization
+
+## Overview
+
+Murphy SDK is loaded from CDN and initialized on the client side using configuration injected from the backend.
+
+---
+
+## Initialization Timeline
+
+```
++-------------------------------------------------------------------+
+|                  MURPHY INITIALIZATION TIMELINE                    |
++-------------------------------------------------------------------+
+|                                                                    |
+|  1. HTML Document Loads                                           |
+|     +----------------------------------------------------------+  |
+|     |  <script nonce="...">                                    |  |
+|     |    var desk_urls = {                                     |  |
+|     |      murphyAppKey: "755747375",                          |  |
+|     |      murphyAppDomain: "murphy.zoho.com",                 |  |
+|     |      murphyAuthKey: "..."                                |  |
+|     |    };                                                     |  |
+|     |  </script>                                                |  |
+|     +----------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  2. InitMurphy() Called                                           |
+|     +----------------------------------------------------------+  |
+|     |  - Checks if Murphy is enabled                           |  |
+|     |  - Fetches build release JSON (for version info)         |  |
+|     |  - Loads Murphy SDK from CDN                             |  |
+|     +----------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  3. Murphy SDK Loaded from CDN                                    |
+|     +----------------------------------------------------------+  |
+|     |  URL: {staticDomain}/murphysdk/3.0.0/murphy.min.js       |  |
+|     |                                                           |  |
+|     |  Creates global: window.murphy                           |  |
+|     +----------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  4. Wait for desk_urls (retry mechanism)                          |
+|     +----------------------------------------------------------+  |
+|     |  - Checks isInitialDataPresent()                         |  |
+|     |  - Retries up to 100 times with 10ms delay               |  |
+|     |  - Ensures desk_urls has Murphy credentials              |  |
+|     +----------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  5. murphyInit() Configures SDK                                   |
+|     +----------------------------------------------------------+  |
+|     |  murphy.install({                                        |  |
+|     |    config: { appKey, appDomain, authKey, ... }           |  |
+|     |  });                                                      |  |
+|     +----------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  6. Client Metrics Installed                                      |
+|     +----------------------------------------------------------+  |
+|     |  murphy.clientmetrics.install(config)                    |  |
+|     |  - Performance monitoring enabled                        |  |
+|     |  - Time to Interactive tracking                          |  |
+|     |  - Soft navigation tracking                              |  |
+|     +----------------------------------------------------------+  |
+|                              |                                     |
+|                              v                                     |
+|  7. Global murphy Object Ready!                                   |
+|     +----------------------------------------------------------+  |
+|     |  murphy.error(...)      -> Track errors                  |  |
+|     |  murphy.appLog(...)     -> Application logs              |  |
+|     |  murphy.clientmetrics   -> Performance metrics           |  |
+|     |  murphy.telemetry       -> User behavior tracking        |  |
+|     +----------------------------------------------------------+  |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Key Files
+
+### 1. initial_html/index.js - Entry Point
+
+```javascript
+// Path: src/library/murphy/initial_html/index.js
+
+import { loadResource } from '../../../_utils/loadResource.js';
+import { isMurphyEnabled, murphyIntegrationName } from './constants.js';
+import { murphySDKUrl } from './Urls.js';
+import {
+  fetchReleaseJson,
+  installMurphyClientMetrics,
+  isClientMetricsSupported,
+  isInitialDataPresent,
+  murphyInit
+} from './utils.js';
+
+export default function InitMurphy() {
+  // Guard: Check if Murphy is enabled
+  if (!isMurphyEnabled || !murphySDKUrl) {
+    return;
+  }
+
+  let initialDataCheckCount = 0;
+  const max_iterations = 100;
+
+  // Load Murphy SDK and build info in parallel
+  Promise.all([
+    isDevMode ? Promise.resolve() : fetchReleaseJson(),
+    loadResource(murphySDKUrl, 'js', murphyIntegrationName, null, false)
+  ]).then(function murphyCb(responseArr) {
+    let [releaseJson = {}] = responseArr;
+
+    try {
+      // Prevent infinite loop
+      if (initialDataCheckCount >= max_iterations) {
+        return;
+      }
+
+      // Wait for desk_urls to be populated
+      if (isInitialDataPresent()) {
+        murphyInit(releaseJson);
+        InitMurphyClientMetrics(releaseJson);
+      } else {
+        // Retry after 10ms
+        setTimeout(() => murphyCb(responseArr), 10);
+      }
+
+      initialDataCheckCount += 1;
+    } catch (ex) {
+      console.log('Init Murphy Error', ex);
+    }
+  });
+}
+
+// Auto-execute on load
+InitMurphy();
+```
+
+### 2. initial_html/utils.js - Core Functions
+
+```javascript
+// Path: src/library/murphy/initial_html/utils.js
+
+import {
+  enableTracking,
+  envi,
+  maxTrackData,
+  pushLogs
+} from './constants';
+
+/**
+ * Check if desk_urls has Murphy configuration
+ */
+export function isInitialDataPresent() {
+  return (
+    globalThis.desk_urls &&
+    typeof globalThis.desk_urls === 'object' &&
+    Boolean(Object.keys(getInitialData()).length)
+  );
+}
+
+/**
+ * Extract Murphy config from desk_urls
+ */
+function getInitialData() {
+  const appDomain = globalThis.desk_urls.murphyAppDomain;
+  const appKey = globalThis.desk_urls.murphyAppKey;
+  const authKey = globalThis.desk_urls.murphyAuthKey;
+  return { appDomain, appKey, authKey };
+}
+
+/**
+ * Initialize Murphy SDK with configuration
+ */
+export function murphyInit(buildInfoJson = {}) {
+  const { appDomain, appKey, authKey } = getInitialData();
+
+  murphy.install({
+    config: {
+      appKey,              // Application identifier
+      appDomain,           // Murphy server domain
+      environment: envi,   // Environment (prod/dev)
+      pushLogs,            // Enable log pushing
+      enableTracking,      // Enable tracking
+      maxTrackData,        // Max tracking data size
+      authKey,             // Authentication key
+
+      // Rage click detection
+      rageClick: {
+        enable: true,
+        tokenLimit: 5
+      },
+
+      // Rage request detection
+      rageRequest: {
+        enable: true
+      },
+
+      // User behavior telemetry
+      telemetry: {
+        enable: true
+      }
+    },
+
+    // Tags attached to all errors
+    setTags() {
+      return {
+        buildId: agentClientVersion,
+        zuid: userInfo.zuid,
+        zgid: currentOrg.id,
+        releaseDetails: {
+          releaseName: buildInfoJson.BuildLabel,
+          releaseRevision: buildInfoJson.Source_Changeset
+        }
+      };
+    }
+  });
+}
+```
+
+---
+
+## Configuration Options
+
+### murphy.install() Config
+
+```
++-------------------------------------------------------------------+
+|  MURPHY.INSTALL() CONFIGURATION OPTIONS                            |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Required:                                                         |
+|  +---------------------------------------------------------------+ |
+|  | appKey      | Application ID from Murphy dashboard            | |
+|  | appDomain   | Murphy server URL (murphy.zoho.com)             | |
+|  | authKey     | Authentication token                            | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  Optional:                                                         |
+|  +---------------------------------------------------------------+ |
+|  | environment | 'production' or 'development'                   | |
+|  | pushLogs    | Enable sending logs to server (boolean)         | |
+|  | maxTrackData| Maximum size of tracking data                   | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
+|  Feature Flags:                                                    |
+|  +---------------------------------------------------------------+ |
+|  | rageClick   | { enable: true, tokenLimit: 5 }                 | |
+|  |             | Detects frustrated clicking                     | |
+|  +---------------------------------------------------------------+ |
+|  | rageRequest | { enable: true }                                | |
+|  |             | Detects repeated failed API calls               | |
+|  +---------------------------------------------------------------+ |
+|  | telemetry   | { enable: true }                                | |
+|  |             | Tracks user behavior patterns                   | |
+|  +---------------------------------------------------------------+ |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+### setTags() - Custom Tags
+
+```javascript
+setTags() {
+  return {
+    // Build identification
+    buildId: agentClientVersion,    // e.g., "2024.01.15.1"
+
+    // User identification
+    zuid: userInfo.zuid,            // Zoho User ID
+    zgid: currentOrg.id,            // Organization ID
+
+    // Release information
+    releaseDetails: {
+      releaseName: buildInfoJson.BuildLabel,
+      releaseRevision: buildInfoJson.Source_Changeset
+    }
+  };
+}
+```
+
+---
+
+## Client Metrics Installation
+
+```javascript
+/**
+ * Install performance monitoring capabilities
+ */
+export function installMurphyClientMetrics(buildInfoJson) {
+  // Set custom tags for all metrics
+  murphy.clientmetrics.setCustomTags({
+    buildId: agentClientVersion,
+    zuid: userInfo.zuid,
+    zgid: currentOrg.id
+  });
+
+  // Set release info for tracking
+  murphy.clientmetrics.setUserEnvInfo({
+    releaseDetails: {
+      buildId: agentClientVersion,
+      releaseName: buildInfoJson.BuildLabel,
+      releaseRevision: buildInfoJson.Source_Changeset
+    }
+  });
+
+  // Configure and install
+  let config = murphy.sendUserInfo();
+  config.isMonitoringEnabled = isMonitoringEnabled();
+  config.clientmetricsWorkerUrl = getWorkerObjectUrl();
+  config.isTimeToInteractiveEnabled = true;
+  config.isClientMetricsSoftNavigationEnabled = true;
+  config.isInterruptionMonitoringEnabled = true;
+
+  murphy.clientmetrics.install(config);
+}
+```
+
+---
+
+## Retry Mechanism
+
+The initialization includes a retry mechanism to handle race conditions:
+
+```
++-------------------------------------------------------------------+
+|  RETRY MECHANISM                                                   |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Problem: desk_urls may not be populated when InitMurphy runs     |
+|                                                                    |
+|  Solution:                                                         |
+|                                                                    |
+|  +------------------+     No      +------------------------+       |
+|  | isInitialData    | ----------> | Wait 10ms              |       |
+|  | Present()?       |             | Increment counter      |       |
+|  +------------------+             | Retry (max 100 times)  |       |
+|          |                        +------------------------+       |
+|          | Yes                               |                     |
+|          v                                   |                     |
+|  +------------------+                        |                     |
+|  | murphyInit()     |                        |                     |
+|  | Initialize SDK   | <----------------------+                     |
+|  +------------------+                                              |
+|                                                                    |
+|  Max Wait Time: 100 * 10ms = 1 second                             |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## SDK Loading
+
+### CDN URL Pattern
+
+```javascript
+// URL is constructed dynamically based on datacenter
+const murphySDKUrl = `${desk_urls.staticDomain}/murphysdk/3.0.0/murphy.min.js`;
+
+// Examples:
+// US: https://static.zohocdn.com/murphysdk/3.0.0/murphy.min.js
+// EU: https://static.zohocdn.eu/murphysdk/3.0.0/murphy.min.js
+// IN: https://static.zohocdn.in/murphysdk/3.0.0/murphy.min.js
+```
+
+### loadResource() Utility
+
+```javascript
+// Loads JavaScript file from CDN
+loadResource(murphySDKUrl, 'js', murphyIntegrationName, null, false);
+```
+
+---
+
+## Global Murphy Object
+
+After initialization, the global `murphy` object is available:
+
+```javascript
+// Check if Murphy is available
+if (typeof murphy !== 'undefined') {
+  // Error tracking
+  murphy.error(error, undefined, { customTags: {...} });
+
+  // Application logging
+  murphy.appLog('INFO', 'User action completed', { userId: 123 });
+
+  // Custom tracking
+  murphy.addCustomTracking({ event: 'feature_used' });
+
+  // Performance metrics
+  murphy.clientmetrics.setTimeToInteractive();
+  murphy.clientmetrics.startSoftNavigation({ from_url, to_url });
+  murphy.clientmetrics.endSoftNavigation();
+}
+```
+
+---
+
+## Summary
+
+```
++-------------------------------------------------------------------+
+|  FRONTEND INIT SUMMARY                                             |
++-------------------------------------------------------------------+
+|                                                                    |
+|  Entry Point: InitMurphy()                                         |
+|  +-- Loads SDK from CDN                                           |
+|  +-- Waits for desk_urls                                          |
+|  +-- Initializes with murphyInit()                                |
+|                                                                    |
+|  Configuration Source: globalThis.desk_urls                        |
+|  +-- murphyAppKey                                                 |
+|  +-- murphyAppDomain                                              |
+|  +-- murphyAuthKey                                                |
+|                                                                    |
+|  Result: Global murphy object with:                                |
+|  +-- murphy.error()          -> Error tracking                    |
+|  +-- murphy.appLog()         -> Application logs                  |
+|  +-- murphy.addCustomTracking() -> Custom events                  |
+|  +-- murphy.clientmetrics    -> Performance monitoring            |
+|  +-- murphy.telemetry        -> User behavior                     |
+|                                                                    |
++-------------------------------------------------------------------+
+```
+
+---
+
+## Related Documents
+
+- [02-MURPHY_ARCHITECTURE.md](./02-MURPHY_ARCHITECTURE.md) - Full architecture
+- [03-MURPHY_BACKEND_CONFIG.md](./03-MURPHY_BACKEND_CONFIG.md) - Backend configuration
+- [05-MURPHY_DESK_CLIENT_USAGE.md](./05-MURPHY_DESK_CLIENT_USAGE.md) - Usage in desk client