GBG ID Scan SDK

A React wrapper for the GBG ID Scan Web SDK, enabling easy integration of document verification and identity scanning in React applications. This package is designed for use with frameworks like Remix.js and includes a vanilla JavaScript API for extensibility to other frameworks (e.g., Svelte, Vue, Angular).

Features

• React Component: A reusable IdScanJourney component for seamless integration in React apps.
• TypeScript Support: Full type definitions for the GBG ID Scan SDK configuration.
• Asset Management: Automated copying of SDK scripts and assets to your app’s public directory.
• Extensibility: Vanilla JavaScript API (initializeIdScan, cleanupIdScan) for non-React environments.
• Browser Compatibility: Safe for server-side rendering (SSR) with frameworks like Remix and Next.js.

Installation

Install the package via npm:

npm install gbg-idscan-sdk

Ensure you have React and React DOM as peer dependencies:

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0"
  }
}

Usage

React/Remix Example

Use the IdScanJourney component in your React or Remix application:

import { IdScanJourney } from 'gbg-idscan-sdk';

function Verify() {
  const config = {
    backendUrl: 'https://poc.idscan.cloud:443',
    token: 'your-token-here', // Replace with your GBG ID Scan token
    journeyDefinitionId: 'b0a201c0-1c18-4b2f-8982-b80756c5647c',
    defaultInputProvider: 'SMART_CAPTURE',
    tripleScanAnalyzerGuidancePage: true,
    fileUploadOnCameraCaptureJourneys: false,
    previewPages: {
      documentStep: { smartCapture: true, manualCapture: true },
      facematchStep: { manualCapture: false },
      poaStep: { manualCapture: false },
      passiveLivenessStep: { manualCapture: false },
      covidStep: { manualCapture: false, fileUpload: true },
    },
    manualCapture: {
      enabled: true,
      timeout: 15,
    },
    smartCapture: {
      timeout: 5000,
      autoStart: true,
      timeLogsEnabled: false,
    },
    isVerboseLogEnabled: false,
    hideLogo: false,
    hideAutoCaptureHints: false,
    basePath: '/', // Matches public/ directory in Remix
  };

  return (
    <div>
      <h1>Document Verification</h1>
      <IdScanJourney {...config} />
    </div>
  );
}

export default Verify;

Props

The IdScanJourney component accepts the following props (based on JourneyContainerConfig):

| Prop | Type | Default | Description | |--------------------------------|--------------------------|-------------------|-----------------------------------------------------------------------------| | backendUrl | string | Required | URL of the GBG ID Scan backend (e.g., https://poc.idscan.cloud:443). | | token | string | Required | Authentication token for the GBG ID Scan SDK. | | journeyDefinitionId | string | Required | Unique ID for the verification journey. | | defaultInputProvider | string | 'SMART_CAPTURE' | Input provider for the journey (e.g., 'SMART_CAPTURE', 'MANUAL'). | | tripleScanAnalyzerGuidancePage | boolean | true | Show guidance page for triple scan analyzer. | | fileUploadOnCameraCaptureJourneys | boolean | false | Allow file uploads on camera capture journeys. | | previewPages | object | {} | Configuration for preview pages (e.g., documentStep, facematchStep). | | manualCapture | object | { enabled: true, timeout: 15 } | Settings for manual capture (enabled, timeout in seconds). | | assetsDirectory | string | 'assets' | Directory for SDK assets (relative to basePath). | | smartCapture | object | { timeout: 5000, autoStart: true, timeLogsEnabled: false } | Smart capture settings. | | isVerboseLogEnabled | boolean | false | Enable verbose logging for debugging. | | hideLogo | boolean | false | Hide the GBG logo in the UI. | | hideAutoCaptureHints | boolean | false | Hide auto-capture hints in the UI. | | basePath | string | '/' | Base URL path for scripts, assets, and styles (e.g., '/' for Remix public/). | | className | string | undefined | CSS class for the container div. | | style | React.CSSProperties | undefined | Inline styles for the container div. |

Additional props can be passed to the underlying JourneyContainer (e.g., onJourneyEvent, templates, dictionary, additionalData).

Assets Setup

The GBG ID Scan SDK requires scripts, assets, and a stylesheet to function. The package includes a postinstall script that automatically copies these files to your application’s public/ directory (e.g., public/scripts/, public/assets/, public/styles.css in Remix).

Steps

1. Install the Package:

   npm install gbg-idscan-sdk

   The postinstall script will copy:

   • src/scripts/ to public/scripts/ (e.g., ides-micro.c7f56e19625c4d2863a9.js).
   • src/assets/ to public/assets/ (e.g., idesmicro_asm.js).
   • src/styles.css to public/styles.css.

2. Verify Files: Ensure your public/ directory contains:

   public/
   ├── scripts/
   │   ├── ides-micro.c7f56e19625c4d2863a9.js
   │   ├── vendor.axios.cee2297d8064255b0106.js
   │   ├── ... (other scripts)
   ├── assets/
   │   ├── idesmicro_asm.js
   └── styles.css

3. Set basePath: In your component, set basePath="/" to match the public/ directory structure.

Manual Asset Copying

If the postinstall script doesn’t run or you need to copy assets manually:

node node_modules/gbg-idscan-sdk/scripts/copy-assets.js

Alternatively, copy gbg-idscan-sdk/src/scripts/, gbg-idscan-sdk/src/assets/, and gbg-idscan-sdk/src/styles.css to your public/ directory.

Building the Package

To build the package for distribution or local testing:

1. Install Dependencies:

   npm install

2. Run Build:

   npm run build

   This runs:

   • npx tsc to compile TypeScript to JavaScript.
   • rollup -c to bundle CommonJS and ES modules into dist/.

The output is:

• dist/index.js (CommonJS)
• dist/index.mjs (ES modules)
• dist/index.d.ts (TypeScript declarations)

Troubleshooting Build Issues

• Error: 'tsc' is not recognized: Ensure TypeScript is installed:

  npm install typescript

  The build script uses npx tsc to run TypeScript locally, so no global installation is needed.

• Rollup Errors: Check rollup.config.js and tsconfig.json for correct paths and settings. Ensure src/index.ts exists.

• Windows-Specific: If running in WebStorm’s terminal, ensure the shell is set to cmd.exe or powershell.exe:

  • Go to File > Settings > Tools > Terminal and update the Shell path.

Testing Locally with Remix

1. Link the Package:

   cd gbg-idscan-sdk
   npm link
   cd ../your-remix-app
   npm link gbg-idscan-sdk

2. Copy Assets: Run the postinstall script or manually copy assets to your-remix-app/public/.

3. Run Remix:

   npm run dev

4. Navigate to the route using IdScanJourney (e.g., /verify).

Extending to Other Frameworks

The package includes a vanilla JavaScript API for use in non-React environments:

import { initializeIdScan, cleanupIdScan } from 'gbg-idscan-sdk';

initializeIdScan({
  backendUrl: 'https://poc.idscan.cloud:443',
  container: document.getElementById('idscan'),
  token: 'your-token-here',
  journeyDefinitionId: 'b0a201c0-1c18-4b2f-8982-b80756c5647c',
  basePath: '/',
}).catch((err) => console.error('Initialization failed:', err));

// Cleanup when done
cleanupIdScan();

This API can be used to create wrappers for Svelte, Vue, Angular, or vanilla JavaScript applications. See src/idScan.ts for implementation details.

Contributing

Contributions are welcome! To contribute:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/your-feature).
3. Commit changes (git commit -m "Add your feature").
4. Push to the branch (git push origin feature/your-feature).
5. Open a pull request.

Please include tests and update documentation as needed.

License

MIT License. See LICENSE for details.

Contact

For issues or questions, open an issue on the GitHub repository or contact [email protected].