Troubleshooting Guide

Common issues and solutions when using the Web Measurement Embedded App (WMEA).

Camera Permission Problems

Symptoms: Empty camera list, camera won't start, or permission denied errors.

Solutions:

• Grant camera permissions: If camera permission was denied initially, WMEA cannot prompt again. Click the lock icon in your browser's address bar and manually grant camera permissions.
• Check browser settings: Navigate to your browser's privacy/security settings and ensure camera access is allowed for your domain.
• Refresh after permission change: After granting permissions, refresh the page and reinitialize the WMEA component.

Performance Issues

Symptoms: Slow measurement startup, frequent cancellations, or poor quality readings.

Solutions:

• Reduce processor load: Close unnecessary browser tabs, applications, and programs that consume CPU/GPU resources.
• Check camera FPS: Ensure your camera supports stable 30 fps. Frame rates below 14 fps will cause measurement cancellation.
• Monitor system resources: Use browser developer tools to check for memory leaks or excessive CPU/GPU usage.

Camera Access Conflicts

Symptoms: Camera fails to start or shows black screen.

Solutions:

• Close conflicting applications: Ensure no other programs (video conferencing, streaming software, etc.) are using the camera.
• Disable screen recording: Stop any screen recording or screen sharing activities during measurement.
• Check virtual camera software: Disable or close any virtual camera applications that might interfere.

Browser Compatibility

Symptoms: Component fails to load, unexpected errors, or missing features.

Solutions:

• Use supported browsers: Ensure you're using a modern, supported browser (Chrome, Safari, Edge).
• Update browser: Use the latest browser version for maximum compatibility.
• Clear browser cache: Clear cache and cookies, then reload the application.
• Disable extensions: Temporarily disable browser extensions that might interfere with camera access or JavaScript execution.

Network and Connectivity Issues

Symptoms: Slow loading, timeout errors, or failed result delivery.

Solutions:

• Check internet connection: Ensure stable internet connectivity for API communication.
• Disable interfering services: Temporarily disable VPNs, proxies, content blockers, or automatic translation services.
• Whitelist domains: Add DeepAffex API domains to your firewall/security software whitelist.
• Check CORS settings: Ensure your server properly handles cross-origin requests if hosting assets separately.

iOS-Specific Issues

Symptoms: Camera access problems or measurement failures on iOS Safari.

Solutions:

• Disable Advanced Tracking Protection: Go to Safari > Advanced > Advanced Tracking and Fingerprinting Protection and turn it off.
• Restart Safari: Close Safari completely and reopen before attempting measurements.
• Check iOS version: Ensure you're using a supported iOS version with up-to-date Safari.

Integration Issues

Component Initialization Failures

Symptoms: WMEA component doesn't appear or throws initialization errors.

Solutions:

• Verify container element: Ensure the container DOM element exists before calling init().
• Check asset paths: Verify that appPath points to correctly hosted WMEA static files.
• Validate configuration: Ensure all required configuration parameters are provided and properly formatted.

// Example proper initialization
const container = document.getElementById('measurement-container');
if (!container) {
  console.error('Container element not found');
  return;
}

measurementApp.init({
  container,
  appPath: './assets', // Verify this path is correct
  settings: {
    token: 'valid-token',
    refreshToken: 'valid-refresh-token',
    studyId: 'valid-study-id',
  },
  // ... other required options
});
Copy

Event Handler Issues

Symptoms: Results or errors not being received.

Solutions:

• Set event handlers before initialization: Assign event handlers immediately after creating the component instance.
• Check event handler syntax: Ensure proper function assignment to event properties.

const measurementApp = new MeasurementEmbeddedApp();

// Set handlers BEFORE calling init()
measurementApp.on.results = (results) => {
  console.log('Results received:', results);
};

measurementApp.on.error = (error) => {
  console.error('Error occurred:', error);
};

// Then initialize
measurementApp.init(options);
Copy

Profile Validation Errors

Symptoms: PROFILE_VALIDATION_FAILED error during initialization.

Solutions:

• Check value ranges: Ensure age, height, and weight are within acceptable ranges.
• Use correct enumerations: Use exact enumeration values for demographic fields.
• Validate BMI calculation: Ensure height/weight combination results in valid BMI.

// Correct profile format
const profile = {
  age: 25, // Check study-specific ranges
  height: 170, // cm
  weight: 70, // kg
  sex: 'ASSIGNED_FEMALE_AT_BIRTH', // Exact enumeration
  smoking: 'SMOKER_FALSE',
  bloodPressureMedication: 'BLOOD_PRESSURE_MEDICATION_FALSE',
  diabetes: 'DIABETES_NONE',
  bypassProfile: false,
};
Copy

Measurement Quality Issues

Low Signal Quality (SNR)

Symptoms: Measurement cancels early with poor signal quality messages.

Solutions:

• Improve lighting: Ensure even, natural lighting on the face without harsh shadows.
• Optimize positioning: Keep face centered within the measurement area and maintain steady position.
• Check environment: Avoid direct sunlight, artificial lighting changes, or moving backgrounds.
• Camera quality: Use a higher-quality camera if available.

Face Detection Problems

Symptoms: Face not detected or tracking issues during measurement.

Solutions:

• Remove obstructions: Ensure glasses, masks, or other items don't obstruct facial features.
• Improve contrast: Ensure good contrast between face and background.
• Check camera angle: Position camera at eye level for optimal face detection.
• Minimize movement: Stay as still as possible during measurement.

Getting Help

If issues persist after trying these solutions:

1. Check browser console: Look for JavaScript errors or network issues in developer tools.
2. Test with minimal setup: Try integration with basic configuration to isolate issues.
3. Verify API credentials: Ensure tokens and study ID are valid and not expired.
4. Review documentation: Check Integration Details for configuration and API requirements.
5. Contact support: Provide browser type, WMEA version, error messages, and steps to reproduce the issue.