Voyage 🚗 #

A comprehensive Flutter plugin for the Kruzr 360 SDK, providing advanced driving analytics, trip monitoring, and user behavior analysis capabilities.

📋 Table of Contents #

• Overview
• Features
• Installation
• Getting Started
• Configuration
• Usage
• API Reference
• Permissions
• Examples
• Support

🌟 Overview #

Voyage is a Flutter plugin that integrates with the Kruzr 360 SDK to provide comprehensive driving analytics and trip monitoring capabilities. It enables developers to build applications with advanced telematics features including real-time trip tracking, driving behavior analysis, user ranking systems, and detailed performance metrics.

✨ Features #

• 🚀 SDK Integration - Easy initialization and platform version detection
• 📱 Trip Monitoring - Automatic trip detection and real-time monitoring
• 👤 User Management - Registration, authentication, and profile management
• 📊 Analytics & Metrics - Comprehensive driving behavior analysis
• 🏆 Leaderboards - User rankings and performance comparison
• 🎖️ Achievements - Track progress across driving behavior categories
• 🔐 OTP Authentication - [DEPRECATED] Secure phone number verification
• 🌐 Data Synchronization - Automatic and manual data sync capabilities
• 🎯 Trip Control - Manual trip start/stop functionality
• 🗺️ Trip Route Visualization – Retrieve full route GeoJSON for rendering
• 📤 Trip Sharing - Generate shareable trip URLs
• 📶 Bluetooth Support - Device scanning and management

📦 Installation #

Add this to your pubspec.yaml file:

dependencies:
  voyage: ^0.0.3-canary.1

Then run:

flutter pub get

🚀 Getting Started #

1. Initializes the Kruzr 360 SDK with the provided configuration. #

This method must be called before using any other functionality of the Kruzr 360 SDK. It establishes the connection with the underlying native SDK and configures various SDK behaviors and settings.

Parameters:

• [kruzr360InitConfig]: Configuration object containing all required initialization settings:
  • licenseKey: Valid license key provided by Kruzr for authentication
  • appName: Name of your application for identification
  • notificationChannelId: Id for the notification channel (Android)
  • shouldTripAutoEnd: Whether trips should automatically end (default: true)
  • shouldTripAutoStart: Whether trips should automatically start (default: true)
  • allowEventSyncRealTime: Whether to sync events in real-time (default: true)

Usage:

try {
  final config = Kruzr360InitConfig(
    licenseKey: 'your-license-key-here',
    appName: 'My Driving App',
    notificationChannelId: 'co.mycompany.myapp.notification.CHANNEL_ID_TELEMATICS',
    shouldTripAutoEnd: true,
    shouldTripAutoStart: true,
    allowEventSyncRealTime: false,
  );
  await Kruzr360Communicator.initializeSDK(config);
  print('SDK initialized successfully');
} catch (e) {
  print('Failed to initialize SDK: $e');
}

Throws:

• Future.error("Unable to initialize SDK"): When the SDK fails to initialize due to platform-specific issues, invalid license key, or other initialization errors.

Platform Exceptions Handled:

• [PlatformException]: Catches platform-specific errors from native Android/iOS code
• [Exception]: Catches any other general exceptions during initialization

Important Notes:

• This is a static method and should be called before creating any instance of [Kruzr360Communicator]
• The method will log detailed error information in debug mode for troubleshooting purposes
• Initialization should typically be done in your main.dart file or during app startup
• Configuration settings affect SDK behavior throughout the app lifecycle

Example Implementation:

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  try {
    final config = Kruzr360InitConfig(
      licenseKey: 'your-license-key',
      appName: 'My App',
      notificationChannelId: 'co.mycompany.myapp.notification.CHANNEL_ID_TELEMATICS',
    );
    await Kruzr360Communicator.initializeSDK(config);
    runApp(MyApp());
  } catch (e) {
    // Handle initialization failure
    print('SDK initialization failed: $e');
    // Show error dialog or fallback UI
   }
}

2. Create a Communicator Instance #

final communicator = Kruzr360Communicator(
  companyName: 'your-company-name',
  accountName: 'your-account-name',
);

3. Set Up Location Services #

communicator.setupLocationStuffs();

⚙️ Configuration #

Android Setup #

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />

📱 Usage #

User Registration and Authentication #

// Register User
final userId = await communicator.registerUserToKruzr(
  driverId: 'unique_driver_123',
  name: 'John Doe',
  countryCode: '+1',
  phoneNumber: '1234567890',
  email: '[email protected]',
);

Trip Monitoring #

// Initiate trip monitoring
await communicator.initiateTripMonitoring();

// Start a trip manually
final started = await communicator.startTrip();

// Get current trip data
final currentTrip = await communicator.getCurrentTripData();

// Stop a trip
final stopped = await communicator.stopTrip();

Analytics and Metrics #

// Get driving summary
final summary = await communicator.getDrivingSummary(
  DateTime.now().subtract(Duration(days: 30)),
  DateTime.now(),
  KruzrPerioicType.weekly,
);

// Get user ranking
final userRank = await communicator.getCurrentUserRank();

// Get leaderboard
final topDrivers = await communicator.getLeaderboardTop10();

// Get user achievements
final achievements = await communicator.fetchMyAchievements();
if (achievements != null) {
  // Check overall achievement progress
  print('Current tier: ${achievements.overall?.currentTier?.value}');
  print('Progress: ${achievements.overall?.count}');
  
  // Check specific category achievements
  if (achievements.speeding != null) {
    print('Speeding tier: ${achievements.speeding!.currentTier?.value}');
    print('Trips to next tier: ${achievements.speeding!.remainingTrips}');
  }
}

Retrieves possible intervention events that occurred during a specific trip. #

Analyzes trip data to identify segments where driving interventions could have been beneficial, such as areas with poor driving behavior, potential safety issues, or coaching opportunities. Each intervention includes location data, timing, and associated scoring statistics.

Parameters:

• [appTripId]: Unique identifier for the trip to analyze

Returns:

• List<PossibleIntervention>: List of intervention events with detailed information

Usage:

try {
  final interventions = await communicator.getPossibleInterventionsForAppTripId('trip-123');
  for (final intervention in interventions) {
    print('Intervention type: ${intervention.scoringType}');
    print('Start time: ${intervention.startTime}');
    print('Location: ${intervention.startAddress}');

    // Check scoring statistics
    if (intervention.scoreStats != null) {
      intervention.scoreStats!.forEach((scoreType, stats) {
        if (stats != null) {
          print('$scoreType - Average: ${stats.average}, Max: ${stats.max}');
        }
      });
    }
  }
} catch (e) {
  print('Failed to get interventions: $e');
}

Throws:

• Future.error("Unable to get possible interventions"): When retrieval fails

Intervention Data Includes:

• Timing: Start and end timestamps in ISO 8601 format
• Location: GPS coordinates and resolved addresses for start/end points
• Scoring: Statistical data for various driving behavior categories
• Type: Classification of the intervention (e.g., "SPEEDING", "HARD_BRAKING", etc.)

Common Intervention Triggers:

• Hard braking events
• Rapid acceleration
• Sharp cornering
• Speeding incidents
• Distracted driving patterns
• Drowsy driving detection

Use Cases:

• Driver coaching and feedback
• Safety analysis and reporting
• Insurance risk assessment
• Fleet management insights
• Training program development

Prerequisites:

• Trip must be completed and processed
• Trip data must be synchronized with servers
• Valid app trip ID is required

🗺️ Fetching Trip Route (GeoJSON) #

Fetch the complete trip route including start/end points, path, and event highlights.

try {
  final route = await communicator.fetchRoute("2985_1764285633333");

  if (route != null) {
    for (final feature in route.collection!) {
      print("Type: ${feature.type}");
      print("Properties: ${feature.properties}");
      print("Geometry: ${feature.geometry?.type}");
    }
  }
} catch (e) {
  print("Failed to fetch route: $e");
}

Route Contains:

1. Route LineString (full trip path)

2. Start and end points

3. Speeding / braking / acceleration event markers

4. Highlight segments with styling metadata

5. Event metadata (startTime, scoreStats, etc.)

Works with any map render engine: MapLibre, Mapbox, flutter_map, Leaflet, or custom painter.

📖 API Reference #

Core SDK Methods #

Trip Monitoring #

User Management #

Analytics & Metrics #

Authentication (OTP) [DEPRECATED] #

Data Management #

Sharing & Bluetooth #

🔐 Permissions #

This plugin requires the following permissions:

Android #

• ACCESS_FINE_LOCATION - For accurate location tracking
• ACCESS_COARSE_LOCATION - For general location services
• ACCESS_BACKGROUND_LOCATION - For background trip monitoring
• BLUETOOTH & BLUETOOTH_ADMIN - For Bluetooth device management

iOS #

• Location permissions will be requested automatically
• Bluetooth permissions for device scanning

💡 Examples #

See the example/ directory for a complete Flutter application demonstrating the usage of the Voyage plugin.

🐛 Issues and Support #

If you encounter any issues or have questions:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information

📄 License #

This project is licensed under the terms specified in the LICENSE file.

🤝 Contributing #

Contributions are welcome! Please read the contributing guidelines before submitting pull requests.

Made with ❤️ by the Kruzr Team