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.