Cashed AR #

A comprehensive Flutter plugin for displaying AR models with intelligent caching on both Android and iOS platforms. Perfect for e-commerce apps, product catalogs, and any application that needs to display 3D models with AR functionality.

🎬 Demo #

🎬 Click the demo above to watch the full video
See Cashed AR in action with real AR model viewing and intelligent caching

Features #

• Cross-Platform AR Support:

  • iOS: Native QuickLook AR viewer with USDZ files
  • Android: model_viewer_plus integration with GLB files
  • Unified API for seamless cross-platform development

• Intelligent Caching System:

  • Smart file caching with automatic cleanup
  • Resume interrupted downloads
  • Chunked downloads for large files
  • URL-based cache validation
  • Configurable cache size limits

• Advanced Download Management:

  • Progress tracking with visual indicators
  • Exponential backoff retry mechanism
  • Network timeout handling
  • File integrity verification
  • Chunked transfer for reliable downloads

• User Experience:

  • Beautiful loading dialogs with progress
  • Error handling with retry options
  • Smooth platform transitions
  • Customizable UI components

• Performance Optimized:

  • Lazy loading of 3D models
  • Efficient memory management
  • Background processing
  • Minimal app size impact

Platform Support #

Installation #

dependencies:
  cashed_ar: ^1.0.0

Quick Start #

Get up and running with Cashed AR in minutes:

1. Add Dependency #

dependencies:
  cashed_ar: ^1.0.0

2. Import Package #

import 'package:cashed_ar/cashed_ar.dart';

3. Basic Usage #

Simple AR Viewer

CashedARViewer(
  androidModelUrl: 'https://example.com/model.glb',
  iosModelUrl: 'https://example.com/model.usdz',
  productId: 'product_123',
  productName: 'Sample Product',
)

Full-Screen AR Modal

await CashedARViewer.showARModal(
  context,
  androidModelUrl: 'https://example.com/model.glb',
  iosModelUrl: 'https://example.com/model.usdz',
  productId: 'product_123',
  productName: 'Sample Product',
);

Android-Only 3D Viewer

CachedModelViewer(
  modelUrl: 'https://example.com/model.glb',
  productId: 'product_123',
  productName: 'Sample Product',
  autoRotate: true,
  ar: true,
)

Configuration Options #

Cache Options #

const cacheOptions = ARCacheOptions(
  maxFileSize: 50 * 1024 * 1024, // 50MB
  maxRetryAttempts: 3,
  chunkSize: 2 * 1024 * 1024, // 2MB chunks
  showLoadingDialog: true,
  showProgress: true,
  connectTimeout: Duration(minutes: 2),
);

Customization #

CashedARViewer(
  androidModelUrl: 'https://example.com/model.glb',
  iosModelUrl: 'https://example.com/model.usdz',
  productId: 'product_123',
  productName: 'Sample Product',
  
  // Android-specific options
  autoRotate: true,
  disableZoom: false,
  disablePan: false,
  cameraControls: 'auto',
  backgroundColor: Colors.black,
  
  // Cache configuration
  cacheOptions: cacheOptions,
  
  // Callbacks
  onModelLoading: () => print('Model loading...'),
  onModelLoaded: () => print('Model loaded!'),
  onError: (error) => print('Error: $error'),
  onIOSARPresented: () => print('iOS AR presented'),
  onIOSARDismissed: () => print('iOS AR dismissed'),
);

Platform-Specific Setup #

iOS Configuration #

No additional configuration required! The plugin automatically handles:

• QuickLook framework integration
• USDZ file support
• Native AR presentation
• File management

Android Configuration #

Add internet permission to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

For AR features, add camera permission (optional):

<uses-permission android:name="android.permission.CAMERA" />
<uses-feature android:name="android.hardware.camera.ar" android:required="false" />

Advanced Usage #

Cache Management #

// Clean up unused cached files
await ARCacheManager.cleanup(
  activeProductIds: ['product_1', 'product_2'],
);

// Check if file is cached
final cachedPath = await ARCacheManager.getCachedFilePath(
  modelUrl: 'https://example.com/model.glb',
  productId: 'product_123',
  platform: ARPlatform.android,
);

Custom Loading and Error Widgets #

CachedModelViewer(
  modelUrl: 'https://example.com/model.glb',
  productId: 'product_123',
  productName: 'Sample Product',
  loadingWidget: CustomLoadingWidget(),
  errorWidget: CustomErrorWidget(),
)

Progress Monitoring #

// Listen to download progress
ValueListenableBuilder<double>(
  valueListenable: ARCacheManager.progressNotifier,
  builder: (context, progress, child) {
    return LinearProgressIndicator(value: progress / 100);
  },
);

API Reference #

CashedARViewer #

The main widget that handles both iOS and Android AR viewing.

CachedModelViewer #

Android-specific 3D model viewer with caching.

ARCacheOptions #

Configuration for caching behavior.

Performance Considerations #

File Size Optimization #

• iOS USDZ files: Recommended < 25MB
• Android GLB files: Recommended < 50MB
• Use compression tools for smaller file sizes

Memory Management #

// The plugin automatically manages memory by:
// - Lazy loading models
// - Cleaning up unused files
// - Using efficient caching strategies

Network Optimization #

const cacheOptions = ARCacheOptions(
  chunkSize: 1 * 1024 * 1024, // 1MB for slower networks
  maxRetryAttempts: 5, // More retries for unstable connections
  connectTimeout: Duration(minutes: 5), // Longer timeout
);

Troubleshooting #

Common Issues #

iOS AR not working

• Ensure device supports ARKit (iOS 11+)
• Check USDZ file format validity
• Verify file is accessible via HTTPS

Android 3D model not loading

• Verify GLB file format
• Check internet connectivity
• Ensure file size is within limits

Caching issues

// Clear all cached files
await ARCacheManager.cleanup(
  activeProductIds: [],
);

Performance issues

• Reduce model complexity
• Use smaller file sizes
• Enable chunked downloads

Debug Mode #

// Enable debug logging
debugPrint('Cache path: ${await getCachedFilePath(...)}');

Examples #

E-commerce Product Viewer #

class ProductARViewer extends StatelessWidget {
  final Product product;
  
  const ProductARViewer({Key? key, required this.product}) : super(key: key);
  
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text(product.name)),
      body: CashedARViewer(
        androidModelUrl: product.androidModelUrl,
        iosModelUrl: product.iosModelUrl,
        productId: product.id,
        productName: product.name,
        onError: (error) {
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text('AR Error: $error')),
          );
        },
      ),
    );
  }
}

Gallery with AR Preview #

class ARGallery extends StatelessWidget {
  final List<Product> products;
  
  @override
  Widget build(BuildContext context) {
    return GridView.builder(
      itemCount: products.length,
      gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(crossAxisCount: 2),
      itemBuilder: (context, index) {
        final product = products[index];
        return Card(
          child: Column(
            children: [
              Expanded(
                child: CashedARViewer(
                  androidModelUrl: product.androidModelUrl,
                  iosModelUrl: product.iosModelUrl,
                  productId: product.id,
                  productName: product.name,
                ),
              ),
              Text(product.name),
            ],
          ),
        );
      },
    );
  }
}

Contributing #

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Development Setup #

1. Clone the repository
2. Run flutter pub get
3. Run the example app: cd example && flutter run

License #

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

Support #

If you have any questions or need help, you can:

• Open an issue
• Check our example for more usage examples
• Read our API documentation
• Contact Ahmed directly: ahmedslem779@gmail.com

Author #

Ahmed Sleem
📧 Email: ahmedslem779@gmail.com
🔗 LinkedIn: linkedin.com/in/sleem98
⭐ GitHub: github.com/sleem2012
📦 pub.flutter-io.cn: pub.flutter-io.cn/publishers/sleem2012

pub.flutter-io.cn • GitHub Repository • Report Issues • Contact