Flutter SDK

For standard implementations, initialize the SDK with just your API key and a navigator key. This provides all essential functionality with default configuration settings that work for most applications.

import 'package:flutter/material.dart';
import 'package:encatch_flutter/encatch_flutter.dart';

final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize the SDK
  encatchFlutter.init(
    '<YOUR_PROJECT_API_KEY>',
    navigatorKey: navigatorKey,
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navigatorKey,
      navigatorObservers: [encatchFlutter.pathObserver],
      home: const HomePage(),
    );
  }
}

For applications requiring custom configuration, the SDK supports advanced initialization options. This approach allows you to specify custom configuration parameters and fine-tune the SDK behavior to match your specific requirements.

import 'package:flutter/material.dart';
import 'package:encatch_flutter/encatch_flutter.dart';

final GlobalKey<NavigatorState> navigatorKey = GlobalKey<NavigatorState>();

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize with advanced configuration
  encatchFlutter.init(
    '<YOUR_PROJECT_API_KEY>',
    navigatorKey: navigatorKey,
    config: encatchConfig(
      host: 'https://your-encatch-instance',
      identity: UserInfo(
        userName: 'user123',
        properties: {
          'email': 'user@example.com',
          'plan': 'premium'
        }
      ),
      isAutoCaptureEnabled: true,
      themeMode: 'light',
      language: 'en',
      useRouterAPI: false,
      ignoredRoutes: ['/settings', '/privacy']
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navigatorKey,
      navigatorObservers: [encatchFlutter.pathObserver],
      home: const HomePage(),
    );
  }
}

encatchConfig Properties:

UserInfo Class:

class UserInfo {
  String userName;
  Map<String, dynamic>? properties;

  UserInfo({
    required this.userName,
    this.properties,
  });
}

Ends the current session and starts a new one while preserving all user data, identity, and state. This method is useful for creating session boundaries without losing user context.

// End current session but keep user data
await encatchFlutter.stopSession();

Use Cases:

• Creating session boundaries
• Preserving user context across session changes
• Session timeout handling
• Application state transitions

Performs a complete reset by starting a new session, clearing user identity, resetting analytics data, and reloading configuration. This returns the SDK to its initial anonymous state.

// Complete session reset
await encatchFlutter.resetSession();

Use Cases:

• User logout (best use case)
• Complete session termination
• Clearing all user data and feedback configurations
• Privacy compliance requirements

Programmatic Feedback Display

Override automatic triggering with manual control over feedback form presentation.

// Open first available feedback
await encatchFlutter.openFeedback();

// Basic usage
await encatchFlutter.openFeedbackById('feedback_config_123');

// With theme and language overrides
await encatchFlutter.openFeedbackById(
  'feedback_config_123',
  theme: 'dark',
  language: 'es'
);

// Open by form title
await encatchFlutter.openFeedbackByName('Product Satisfaction Survey');

// With customization options
await encatchFlutter.openFeedbackByName(
  'Feature Feedback',
  theme: 'dark',
  language: 'fr'
);

Best Practice: Use feedback IDs for programmatic control and names for content-driven scenarios. IDs are more stable across configuration changes.

Custom Events: Track specific events that are unique to your application's needs and business logic using the trackEvent method.

trackEvent(String eventName, [Map<String, dynamic>? properties])

Use Cases:

• User behavior analytics
• Feature usage tracking
• Conversion funnel analysis
• Custom business metrics
• Application-specific interactions
• A/B test tracking
• User journey mapping

Parameters:

Example Usage:

// Basic event tracking
await encatchFlutter.trackEvent('page_view');

// E-commerce events
await encatchFlutter.trackEvent('purchase_completed', {
  'product_id': 'prod_123',
  'amount': 99.99,
  'currency': 'USD',
  'category': 'electronics',
  'quantity': 2,
  'payment_method': 'credit_card'
});

// User interaction tracking
await encatchFlutter.trackEvent('button_click', {
  'button_id': 'cta-subscribe',
  'location': 'hero-section',
  'action': 'newsletter_signup'
});

// Feature usage tracking
await encatchFlutter.trackEvent('feature_used', {
  'feature': 'advanced_search',
  'filters_applied': ['price', 'category', 'rating'],
  'results_count': 25,
  'search_time': 1.2
});

// Video engagement
await encatchFlutter.trackEvent('video_interaction', {
  'video_id': 'tutorial_101',
  'action': 'play',
  'current_time': 45,
  'total_duration': 180,
  'quality': '720p'
});

// Form analytics
await encatchFlutter.trackEvent('form_step_completed', {
  'form_name': 'onboarding',
  'step': 2,
  'step_name': 'personal_info',
  'time_spent': 120,
  'completion_rate': 0.75
});

Event Enhancement: The SDK automatically enriches tracked events with:

• Current page path and title
• Session information and user identity
• Device and browser metadata
• Timestamp and user agent
• Geographic location (if available)

Navigation Tracking: The SDK provides automatic navigation tracking through Flutter's RouteObserver. You must add the path observer to your MaterialApp's navigatorObservers to enable automatic screen tracking.

Important: This is essential for the SDK to track user navigation patterns and determine when to show relevant feedback forms.

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorKey: navigatorKey,
      navigatorObservers: [encatchFlutter.pathObserver], // Add this line
      initialRoute: '/',
      routes: {
        '/': (context) => HomePage(),
        '/profile': (context) => ProfilePage(),
      },
    );
  }
}

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  encatchFlutter.init(
    '<YOUR_PROJECT_API_KEY>',
    navigatorKey: navigatorKey,
    config: encatchConfig(
      useRouterAPI: true, // Enable Router API support
      // ... other config
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp.router(
      routerConfig: _router,
      // ... other configuration
    );
  }
}

Auto-captured Navigation Events: The SDK automatically tracks navigation events without any manual implementation required.

Configuration:

// Disable automatic navigation tracking
encatchFlutter.init(
  '<YOUR_PROJECT_API_KEY>',
  navigatorKey: navigatorKey,
  config: encatchConfig(
    isAutoCaptureEnabled: false
  ),
);

// Enable specific auto-events only
encatchFlutter.init(
  '<YOUR_PROJECT_API_KEY>',
  navigatorKey: navigatorKey,
  config: encatchConfig(
    isAutoCaptureEnabled: true,
    ignoredRoutes: ['/settings', '/privacy'] // Exclude specific routes
  ),
);

Use Cases:

• Basic user behavior analytics without custom implementation
• Screen engagement and navigation tracking
• User journey analysis
• App usage patterns
• Screen flow optimization

Automatic Context Enrichment: All auto-captured navigation events are automatically enhanced with:

• Current screen path and title
• Session information and user identity
• Device and platform metadata
• Timestamp and user agent
• Geographic location (if available)

setTheme(String theme)

Example Usage:

// Basic theme switching
await encatchFlutter.setTheme('dark');   // Switch to dark theme
await encatchFlutter.setTheme('light');  // Switch to light theme

Use Cases:

• Dark mode toggle implementation
• System theme synchronization
• User preference persistence
• Accessibility compliance

setLanguage(String languageCode)

Example Usage:

// Language localization
await encatchFlutter.setLanguage('es');      // Spanish
await encatchFlutter.setLanguage('fr');      // French
await encatchFlutter.setLanguage('de');      // German
await encatchFlutter.setLanguage('YOUR_ADMIN_CONFIG_LANGUAGE_CODE');

Use Cases:

• Internationalization (i18n) implementation
• Multi-language application support
• User language preference persistence
• Browser language detection and fallback

Note: Language changes affect all subsequent feedback forms. You may ideally call this when user switches languages in your application.