ATX Embedded App

A lightweight, embeddable proctoring client that can be integrated into host applications with proper isolation and encapsulation.

Overview

The ATX Embedded App is a proctoring solution designed to be embedded into host applications. It uses Shadow DOM for isolation and provides a clean API for integration. The application handles various proctoring flows including device checks, permissions management, and user instructions.

Features

• Shadow DOM Encapsulation: Ensures the embedded app doesn't interfere with the host application's styles and DOM
• Global API: Simple integration via window.Proview.init() and window.Proview.destroy()
• Comprehensive Proctoring Flows:
  • Device compatibility checks
  • Camera and microphone permissions
  • Screen sharing setup
  • Custom instructions support
  • Photo ID verification
  • Secondary device instructions
  • Privacy policy compliance
• Error Handling: Built-in handling for browser, device, and OS compatibility issues

Technology Stack

• Frontend: React 18 with TypeScript
• State Management: Redux with Redux Toolkit and Redux Saga
• Routing: React Router (memory router for embedded context)
• Styling: Tailwind CSS
• Build System: Rspack for bundling, Nx for project management
• Testing: Jest

Installation

# Install dependencies
npm install
# or
yarn install

Development

# Run development server
nx serve atx-embedded-app
# or
yarn nx serve atx-embedded-app

The development server will start at http://localhost:4202

Building

# Build for production
nx build atx-embedded-app
# or
yarn nx build atx-embedded-app

This will generate a UMD bundle (init.js) that can be integrated into host applications.

Production Server

To serve the production build for testing:

# Serve production build
nx serve-build atx-embedded-app
# or
yarn nx serve-build atx-embedded-app

The production server will start at http://localhost:4201

Docker Build

To build a Docker container for the application:

# Build container for remote registry
nx container atx-embedded-app

# Build container locally
nx container-local atx-embedded-app

Integration

To integrate the ATX Embedded App into a host application:

1. Include the built JavaScript bundle in your HTML:

<script src="path/to/init.js"></script>

2. Initialize the client with your configuration:

window.Proview.init({
  projectSecret: 'your-secret-key',
  autoStart: true,
  candidate: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    externalId: 'user-123',
    // Additional candidate data...
  },
  workflow: {
    name: 'Test Workflow',
    externalId: 'workflow-123',
    externalAttemptId: 'attempt-456',
    proctoringType: 'remote_invigilation',
    // Additional workflow data...
  },
  callbacks: {
    onConnected: (api) => {
      // Handle API ready
      console.log('Proctoring client connected');

      // Use the API to communicate with the embedded app
      api.sendMessage({ type: 'CUSTOM_EVENT', payload: {} });
    },
    onDisconnected: () => {
      // Handle disconnection
      console.log('Proctoring client disconnected');
    },
    onError: (error) => {
      // Handle errors
      console.error('Proctoring client error:', error);
    },
  },
});

3. When done, destroy the client:

window.Proview.destroy();

Project Structure

• /src: Source code
  • /app: Main application components
  • /assets: Static assets
  • /context: React context providers
  • /demo: Demo implementation
  • /dev: Development utilities
  • /prod: Production components including ShadowWrapper
  • /routes.tsx: Application routes
  • /store: Redux store configuration
  • /types: TypeScript type definitions
  • /utils: Utility functions

Shadow DOM Implementation

The embedded app uses a shadow DOM approach for isolation. The main entry point is in /src/prod/main.tsx which exposes an init function that gets attached to the window as window.Proview.init. When initialized, it creates a shadow DOM container and renders the React app inside it.

The app uses React Router with memory router for navigation. Routes are defined in /src/routes.tsx.

The ShadowWrapper component in /src/prod/ShadowWrapper.tsx handles the shadow DOM creation and injects the CSS.

Working with SVGs

SVG files in this project are configured to be used as React components by default. This allows for easier styling and manipulation:

// Import SVG as a React component
import IconComponent from './path/to/icon.svg';

// Use it directly as a component
<IconComponent />;

If you need to use an SVG as an image source (for <img> tags), add the ?url query parameter:

// Import SVG as a URL
import iconUrl from './path/to/icon.svg?url';

// Use it with an img tag
<img src={iconUrl} alt="Icon description" />;

Testing

# Run tests
nx test atx-embedded-app
# or
yarn nx test atx-embedded-app

License

[Your license information here]

Support

For support or questions, please contact [your support contact information].