vigil_sdk_flutter

Vigil Flutter SDK

A comprehensive Flutter SDK for API Monitoring, Job Monitoring, and Error Monitoring in Flutter applications.

---

Installation

Add this to your pubspec.yaml:

dependencies:
  vigil_sdk_flutter: ^1.0.0

Then run : fvm flutter pub get

Project now uses Flutter SDK : SDK Version : 3.29.3

Setup and Initialization Initialize the Vigil SDK in your Flutter application's main function or early in your app lifecycle:

import 'package:vigil_sdk_flutter/vigil.dart';
import 'package:vigil_sdk_flutter/models/vigil_options.dart';

void main() {
  // Initialize Vigil with basic options
  Vigil.initialize(
    VigilOptions(
      apiKey: 'your-api-key-here',
      clientVersion: '1.0.0',
      instanceUrl: 'https://your-vigil-instance.com',
    ),
  );

  runApp(MyApp());
}

API Monitoring

The Vigil Flutter SDK provides automatic API monitoring through HTTP interceptors.

Basic Setup

import 'package:http_interceptor/http_interceptor.dart';
import 'package:vigil_sdk_flutter/interceptors/vigil_interceptor.dart';
import 'package:vigil_sdk_flutter/types/api_monitoring_types.dart';

// Configure API monitoring with options
Vigil.configureApiMonitoring(ApiMonitoringOptions(
  exclude: ExcludeOptions(
    get: ['/health', '/ping'],
    post: ['/api/v1/app-health-check'],
  ),
  include: IncludeOptions(
    get: ['^/api/v1/*'],
    post: ['^/api/v1/*']
  ),
  maskAttributes: ['authorization', 'password', 'token']
));

// Create HTTP client with Vigil interceptor
final client = InterceptedClient.build(
  interceptors: [VigilInterceptor()],
);

// Use the client for your HTTP requests
final response = await client.get(Uri.parse('https://api.example.com/data'));

API Monitoring Options

ExcludeOptions

Excludes specific API endpoints from monitoring

IncludeOptions

Explicitly defines which API endpoints should be monitored

maskAttributes

Sensitive data fields that should be masked in monitoring logs

Pattern Matching

-- Exact match: /api/v1/users -- Regex patterns: ^/api/v1/.* (starts with /api/v1/) -- Parameterized routes: /api/v1/users/0-9+ (users with numeric IDs)

Precedence Rules

-- If both exclude and include are empty, all APIs are monitored by default -- exclude patterns are checked first and take precedence over include -- If an endpoint matches both include and exclude patterns, it will be excluded

Error Monitoring

Capture and monitor exceptions that occur in your Flutter application

import 'package:vigil_sdk_flutter/error_manager.dart';
import 'package:vigil_sdk_flutter/models/exception_models.dart';

// Basic error capturing
try {
  // Your code that might throw an exception
  int result = 10 ~/ 0;
} catch (error, stackTrace) {
  ErrorManager.captureException(error);
}

Error Monitoring with Additional Context

try {
  // Your code here
  await fetchUserData(userId);
} catch (error, stackTrace) {
  // Capture exception with additional context
  ErrorManager.captureException(
    error,
    ExceptionOptions(
      tags: ['user-data', 'network-error'],
      context: {
        'userId': userId,
        'timestamp': DateTime.now().toIso8601String(),
        'userAgent': 'Flutter App v1.0.0',
        'additionalInfo': 'User was trying to fetch profile data'
      }
    )
  );
}

Job Monitoring

To ensure monitoring of jobs within the application, integrate the following code snippet wherever jobs are defined and executed:

// Import JobManager to monitor the Jobs in the application
import 'package:vigil_sdk_flutter/job_manager.dart';
import 'package:vigil_sdk_flutter/models/job_monitoring_models.dart';

// Job function
Future<void> jobFunc() async {
  try {
    // Log that the job triggered with a start message
    final startJobDetail = JobDetail(
      jobId: "<job-id>",
      jobSlug: "<job-slug>",
      message: "<job-start-message>",
      eventTime: DateTime.now(),
      clientVersion: "1.0.0"
    );
    await JobManager.captureJobStart(startJobDetail);

    // Your job logic here
    // ...
    // ...

    // Log that the job has completed its execution with a success message
    final stopJobDetail = JobDetail(
      jobId: "<job-id>",
      jobSlug: "<job-slug>",
      message: "<job-end-message>",
      eventTime: DateTime.now(),
      clientVersion: "1.0.0"
    );
    await JobManager.captureJobEnd(stopJobDetail);

  } catch (error) {
    // Log job failure with error details
    final failJobDetail = JobDetail(
      jobId: "<job-id>",
      jobSlug: "<job-slug>",
      message: "<job-failure-message>: ${error.toString()}",
      eventTime: DateTime.now(),
      clientVersion: "1.0.0"
    );
    await JobManager.captureJobFailure(failJobDetail);
  }
}

Either jobId or jobSlug should be provided with values. Neither of these values should be empty in order to pass to JobDetail and all other parameters are optional.