Cordova Diagnostics Viewer Plugin

A lightweight, in-app viewer for device logs with configurable reporting functionality. Perfect for customer support scenarios and debugging in production environments.

Features

• In-app log viewer: Modal overlay with scrollable textarea showing device logs
• Pure JavaScript UI: Rendered in WebView, no native UI components required
• Self-contained styling: CSS automatically injected, no external files needed
• Configurable send handler: Host app decides how to send logs (HTTP POST, email, etc.)
• Log redaction: Optional callback to redact sensitive information
• Theme support: CSS custom properties with Bootstrap integration
• Responsive design: Works on all screen sizes
• Easy integration: Simple API with comprehensive configuration options

Installation

Via Cordova CLI

cordova plugin add cordova-plugin-diagnostics-viewer

Via npm

npm install cordova-plugin-diagnostics-viewer
cordova plugin add cordova-plugin-diagnostics-viewer

Dependencies

This plugin requires cordova-plugin-native-logs for accessing device logs:

cordova plugin add cordova-plugin-native-logs

Quick Start

// Initialize on device ready
document.addEventListener('deviceready', function() {
  DiagnosticsViewer.init({
    title: 'My App Diagnostics',
    sendHandler: function(logs) {
      // Send logs to your support system
      fetch('/api/support/logs', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ logs: logs })
      });
    }
  });
}, false);

// Open from anywhere in your app
function showDiagnostics() {
  DiagnosticsViewer.open();
}

API Reference

DiagnosticsViewer.init(options)

Initialize the diagnostics viewer with configuration options.

Parameters:

• options (Object): Configuration object
  • title (string): Modal title (default: "Diagnostics")
  • lineLimit (number): Maximum lines to display (default: 1000)
  • redactionCallback (Function): Optional callback to redact sensitive data
  • sendHandler (Function): Callback to handle sending logs
  • metaItems (Array): Optional metadata items to display
  • theme (Object): Theme customization options

Example:

DiagnosticsViewer.init({
  title: 'App Diagnostics',
  lineLimit: 500,
  redactionCallback: function(logs) {
    // Remove sensitive information
    return logs.replace(/password=\w+/gi, 'password=***');
  },
  sendHandler: function(logContent) {
    // Send logs via HTTP POST
    fetch('/api/support/logs', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ logs: logContent })
    });
  },
  metaItems: [
    { label: 'App Version', value: '1.2.3' },
    { label: 'User ID', value: getCurrentUserId() }
  ]
});

DiagnosticsViewer.open()

Opens the diagnostics viewer modal and loads current device logs.

DiagnosticsViewer.open();

DiagnosticsViewer.close()

Closes the diagnostics viewer modal.

DiagnosticsViewer.close();

DiagnosticsViewer.setSendHandler(handler)

Set or update the send handler at runtime.

Parameters:

• handler (Function): Function to handle sending logs

Example:

DiagnosticsViewer.setSendHandler(function(logContent) {
  // Email logs
  cordova.plugins.email.open({
    to: '[email protected]',
    subject: 'App Diagnostics',
    body: logContent,
    isHtml: false
  });
});

DiagnosticsViewer.setMetaItems(items)

Set metadata items to display at runtime.

Parameters:

• items (Array): Array of objects with label and value properties

DiagnosticsViewer.setMetaItems([
  { label: 'Session ID', value: getSessionId() },
  { label: 'Network', value: getNetworkStatus() }
]);

Advanced Usage

Theme Customization

DiagnosticsViewer.init({
  theme: {
    vars: {
      'diag-accent': '#007bff',
      'diag-bg': '#ffffff',
      'diag-text': '#333333'
    }
  }
});

Security & Redaction

DiagnosticsViewer.init({
  redactionCallback: function(logs) {
    return logs
      .replace(/email=[\w@.-]+/gi, 'email=***')
      .replace(/token=[\w-]+/gi, 'token=***')
      .replace(/password=\w+/gi, 'password=***')
      .replace(/api_key=[\w-]+/gi, 'api_key=***');
  }
});

Integration with Error Reporting

DiagnosticsViewer.init({
  sendHandler: function(logContent) {
    const payload = {
      logs: logContent,
      timestamp: new Date().toISOString(),
      deviceInfo: {
        platform: device.platform,
        version: device.version,
        model: device.model,
        uuid: device.uuid
      },
      appInfo: {
        version: getAppVersion(),
        buildNumber: getBuildNumber()
      }
    };
    
    // Send to your error reporting service
    return fetch('/api/diagnostics', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    }).then(response => {
      if (response.ok) {
        showToast('Diagnostics sent successfully');
        DiagnosticsViewer.close();
      } else {
        throw new Error('Failed to send diagnostics');
      }
    });
  }
});

UI Components

The modal includes:

• Title bar: Configurable title with close button
• Log display: Scrollable, editable text area showing device logs
• Metadata section: Optional app/device information display
• Statistics: Line count and data size information
• Action buttons:
  • Refresh: Reload logs from device
  • Send: Call the configured send handler with current content
  • Close: Close the modal

Platform Support

• iOS: 5.0+
• Android: 8.0+ (API level 26+)
• Cordova: 9.0+

Dependencies

• cordova-plugin-native-logs: Required for accessing device logs

Browser Development

When running in browser (not on device), the plugin will show a message that device logs are not available. This allows for testing the UI during browser development.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for release history.

License

MIT License - see LICENSE file for details.