SnapCap Flutter SDK

A Flutter SDK for document capture and analysis using camera and WASM models. Easy to integrate and distribute.

Features

• 📱 Flutter Native: Built entirely in Flutter for cross-platform compatibility
• 📷 Camera Integration: Direct camera access for high-quality image capture
• 🌐 WebView Integration: Loads local webapp with WASM models for analysis
• 🔒 Permission Handling: Automatic camera and storage permission management
• ⚡ Easy Integration: Simple function calls to start document capture
• 📦 Asset Bundling: Includes webapp and WASM models in the package
• 🎯 Customizable: Configurable image quality, max images, and more

Installation

Option 1: Git Dependency (Recommended for easy updates)

Add this to your pubspec.yaml:

dependencies:
  snapcap_flutter_sdk:
    git:
      url: https://github.com/your-org/snapcap_flutter_sdk.git
      ref: main

Option 2: Local Path (For development/testing)

dependencies:
  snapcap_flutter_sdk:
    path: ../snapcap_flutter_sdk

Option 3: Published Package (When available)

dependencies:
  snapcap_flutter_sdk: ^0.0.1

Quick Start

1. Initialize the SDK

import 'package:snapcap_flutter_sdk/snapcap_flutter_sdk.dart';

void main() async {
  // Initialize the SDK with your configuration
  final config = SnapCapConfig(
    token: 'YOUR_API_TOKEN',
    cpf: 'USER_CPF_NUMBER', // Optional
    environment: SnapCapEnvironment.dev,
    maxImages: 5,
    imageQuality: 0.8,
  );
  
  await SnapCapSDK.instance.initialize(config);
  
  runApp(MyApp());
}

2. Start Document Capture

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('SnapCap Demo')),
      body: Center(
        child: ElevatedButton(
          onPressed: () => _startDocumentCapture(context),
          child: Text('Start Document Capture'),
        ),
      ),
    );
  }
  
  Future<void> _startDocumentCapture(BuildContext context) async {
    try {
      await SnapCapSDK.instance.startDocumentCapture(
        context,
        callback: MySnapCapCallback(),
      );
    } catch (e) {
      print('Error starting document capture: $e');
    }
  }
}

3. Implement Callbacks

class MySnapCapCallback implements SnapCapCallback {
  @override
  void onEvent(String event) {
    print('SDK Event: $event');
  }
  
  @override
  void onError(SnapCapError error) {
    print('SDK Error: ${error.message}');
  }
  
  @override
  void onDocumentCaptureComplete(SnapCapResult result) {
    print('Document capture complete!');
    print('Images: ${result.imagePaths}');
    print('Analysis: ${result.analysisData}');
    
    // Handle the captured images and analysis results
    _processResults(result);
  }
  
  @override
  void onCancelled() {
    print('Document capture was cancelled');
  }
  
  // Implement other callback methods as needed...
  @override
  void onLoadingEnd() {}
  @override
  void onProcessingStatus(SnapCapProcessingStatus status) {}
  @override
  void onCameraReady() {}
  @override
  void onWebappLoaded() {}
  @override
  void onWasmModelsLoaded() {}
  
  void _processResults(SnapCapResult result) {
    // Process the captured images and analysis data
    // You can save images, send to server, etc.
  }
}

Configuration Options

SnapCapConfig

Parameter	Type	Default	Description
token	String	Required	API token for authentication
cpf	String?	null	User's CPF number (Brazilian ID)
base64Photo	String?	null	Base64 encoded registration photo
environment	SnapCapEnvironment	dev	Environment (dev/stg/prd)
useTwa	bool	false	Use Trusted Web Activity
fallbackToWebView	bool	true	Fallback to WebView if TWA fails
customWebappUrl	String?	null	Custom webapp URL
customModelsUrl	String?	null	Custom WASM models URL
maxImages	int	5	Maximum number of images to capture
imageQuality	double	0.8	Image quality (0.1 to 1.0)
debugMode	bool	false	Enable debug mode
customHeaders	Map<String, String>	{}	Custom headers for requests

Environment Types

enum SnapCapEnvironment {
  dev,    // Development
  stg,    // Staging
  prd,    // Production
}

Error Handling

The SDK provides comprehensive error handling through the SnapCapError enum:

enum SnapCapError {
  invalidConfig,           // Invalid configuration
  cameraPermissionDenied,  // Camera permission denied
  cameraNotAvailable,      // Camera not available
  webViewError,            // WebView error
  networkError,            // Network error
  wasmModelError,          // WASM model loading error
  documentProcessingError, // Document processing error
  unknown,                 // Unknown error
}

Result Handling

The SnapCapResult class contains all the captured data:

class SnapCapResult {
  final List<String> imagePaths;           // Paths to captured images
  final Map<String, dynamic> analysisData; // Analysis results from WASM
  final SnapCapProcessingStatus status;    // Processing status
  final DateTime timestamp;                // When result was generated
  final Map<String, dynamic> metadata;     // Additional metadata
}

Advanced Usage

Custom Webapp Integration

final config = SnapCapConfig(
  token: 'YOUR_TOKEN',
  customWebappUrl: 'https://your-custom-webapp.com',
  customModelsUrl: 'https://your-models.com',
);

Debug Mode

final config = SnapCapConfig(
  token: 'YOUR_TOKEN',
  debugMode: true, // Enables detailed logging
);

Custom Headers

final config = SnapCapConfig(
  token: 'YOUR_TOKEN',
  customHeaders: {
    'X-Custom-Header': 'value',
    'Authorization': 'Bearer token',
  },
);

Platform Support

• ✅ Android: Full support with camera and WebView
• ✅ iOS: Full support with camera and WebView
• ❌ Web: Not supported (requires camera access)
• ❌ Desktop: Limited support (no camera access)

Permissions

The SDK automatically requests these permissions:

• Camera: Required for document capture
• Storage: Required for saving captured images

Troubleshooting

Common Issues

1. Camera Permission Denied

   • Ensure camera permission is granted in app settings
   • Check if camera is available on the device

2. WebView Not Loading

   • Verify internet connection if using custom webapp
   • Check if bundled webapp assets are properly included

3. WASM Models Not Loading

   • Ensure WASM models are properly bundled
   • Check browser compatibility

Debug Mode

Enable debug mode to get detailed logging:

final config = SnapCapConfig(
  token: 'YOUR_TOKEN',
  debugMode: true,
);

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support and questions:

• 📧 Email: support@snapcap.com
• 📱 GitHub Issues: Create an issue
• 📚 Documentation: Full documentation

Changelog

Version 0.0.1

• Initial release
• Basic document capture functionality
• Camera integration
• WebView integration
• WASM model support
• Permission handling
• Error handling
• Callback system