Advanced Configuration

This guide covers advanced configuration options for the GOFA WebView SDK.

Highlights

Flexible callback configuration for WebView events
Environment-based configuration using helper classes and environment variables
Secure authentication with client credentials and Firebase custom tokens
Customizable navigation URLs for different GOFA services
Support for custom headers
Build-time and runtime configuration via Dart defines
Configuration validation with clear error handling
Troubleshooting tips and configuration best practices

When embedding the GOFA web app in your Flutter app using the WebView SDK, the web app communicates important events back to Flutter via the updateCallback function you provide to WebViewSdkManager.

The web app posts messages using the postMessage API. The Flutter SDK receives these messages and invokes your updateCallback with the event name and event data.

Basic Event Handler Setup

Basic Event Handler Configuration

final webViewSdkManager = WebViewSdkManager(
  environment: Environment.DEV,
  updateCallback: (String eventName, dynamic eventData) {
    // Handle different event types
    switch (eventName) {
      case 'START_ASSESSMENT':
        // Handle assessment initiation
        _handleAssessmentStart(eventData);
        break;
      case 'FINISH_ASSESSMENT':
        // Handle assessment completion
        _handleAssessmentFinish(eventData);
        break;
      case 'GENERATED_REPORT':
        // Handle report generation
        _handleReportGenerated(eventData);
        break;
      case 'EARLY_QUIT':
        // Handle early exit scenarios
        _handleEarlyQuit(eventData);
        break;
      default:
        print('Unknown event: $eventName');
    }
  },
);

Tip: The updateCallback receives the event name and a data map. You can use this to trigger navigation, analytics, or other business logic in your Flutter app.

Event Details

For specific event types and data structures for different GOFA modules (such as MSK assessments), refer to the respective integration guides:

MSK Integration Guide - Complete MSK event handling

Event Data Structure

Most events follow a consistent data structure pattern:

// Common event data fields
{
  'eventId': 'unique-event-identifier',
  'timestamp': 'iso-date-string',
  'userId': 'user-identifier',
  'moduleType': 'msk|wellness|other',
  // Additional event-specific data
}

Environment Helper Class

Create a helper class for environment-specific configuration:

class EnvironmentConfig {
  static const String _envString = String.fromEnvironment('GOFA_ENVIRONMENT', defaultValue: 'DEV');
  static const String clientId = String.fromEnvironment('GOFA_CLIENT_ID');
  static const String clientSecret = String.fromEnvironment('GOFA_CLIENT_SECRET');
  static const String clientUserId = String.fromEnvironment('GOFA_CLIENT_USER_ID');

  /// Converts the GOFA_ENVIRONMENT string to the SDK enum.
  static Environment get environment {
    switch (_envString.toUpperCase()) {
      case 'PRD': return Environment.PRD;
      case 'UAT': return Environment.UAT;
      default:   return Environment.DEV;
    }
  }

  static bool get isProduction => environment == Environment.PRD;

  static String get baseUrl {
    switch (environment) {
      case Environment.PRD: return 'https://client.gofa.app';
      case Environment.UAT: return 'https://client.uat.gofa.app';
      default: return 'https://client.dev.gofa.app';
    }
  }
}

URL Examples

Route Registration Required

If you navigate with Navigator.pushNamed(..., GofaWebView.routeName, ...), ensure GofaWebView.routeName is registered in your app's MaterialApp.routes first.


Navigator.pushNamed(
  context,
  GofaWebView.routeName,
  arguments: {
    // Example: MSK (Musculoskeletal) services
    'url': 'https://your-client.gofa.app/msk/home',
    'clientId': clientId,
    'locale': const Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hant',
    ),
  },
);

Authentication Configuration

Client Credentials

Configure your application's authentication credentials:

const clientId = String.fromEnvironment('GOFA_CLIENT_ID', defaultValue: 'your-client-id');
const clientSecret = String.fromEnvironment('GOFA_CLIENT_SECRET', defaultValue: 'your-client-secret');
const clientUserId = String.fromEnvironment('GOFA_CLIENT_USER_ID', defaultValue: 'unique-user-id');

Basic Authentication (Deprecated)

Deprecated — Removed in v1.1.0

HTTP Basic Auth for MSK routes has been replaced by Firebase custom token authentication. The basicAuthUser and basicAuthPass parameters are deprecated and will be removed in a future version. You can safely omit them. See MSK Authentication for the current auth flow.

Custom Headers

You can configure custom headers for WebView requests:

// The SDK automatically handles authentication headers
// Custom headers can be added through the initialization process
await webViewSdkManager.init(
  clientId: clientId,
  clientSecret: clientSecret,
  clientUserId: clientUserId,
  environment: EnvironmentConfig.environment,
);

Runtime Configuration

Environment Variables

Set up environment variables for different build configurations:

# Development build
flutter build apk --dart-define=GOFA_ENVIRONMENT=DEV \
                  --dart-define=GOFA_CLIENT_ID=dev-client-id \
                  --dart-define=GOFA_CLIENT_SECRET=dev-secret

# UAT build
flutter build apk --dart-define=GOFA_ENVIRONMENT=UAT \
                  --dart-define=GOFA_CLIENT_ID=uat-client-id \
                  --dart-define=GOFA_CLIENT_SECRET=uat-secret

# Production build
flutter build apk --dart-define=GOFA_ENVIRONMENT=PRD \
                  --dart-define=GOFA_CLIENT_ID=prod-client-id \
                  --dart-define=GOFA_CLIENT_SECRET=prod-secret

Configuration Validation

Validation Function

Create a validation function to ensure proper configuration:

class ConfigValidator {
  static Future<bool> validateConfiguration() async {
    // Check environment
    if (![Environment.DEV, Environment.UAT, Environment.PRD].contains(EnvironmentConfig.environment)) {
      print('❌ Invalid environment: ${EnvironmentConfig.environment}');
      return false;
    }
    // Check required credentials
    if (EnvironmentConfig.clientId.isEmpty) {
      print('❌ CLIENT_ID is required');
      return false;
    }
    if (EnvironmentConfig.clientSecret.isEmpty) {
      print('❌ CLIENT_SECRET is required');
      return false;
    }
    if (EnvironmentConfig.clientUserId.isEmpty) {
      print('❌ CLIENT_USER_ID is required');
      return false;
    }
    // Validate production settings
    if (EnvironmentConfig.isProduction) {
      if (EnvironmentConfig.clientId == 'abc' ||
          EnvironmentConfig.clientSecret == 'abcSecret') {
        print('❌ Cannot use default credentials in production');
        return false;
      }
    }
    print('✅ Configuration validation passed');
    return true;
  }
}

// Use in your app initialization
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (await ConfigValidator.validateConfiguration()) {
    runApp(const MyApp());
  } else {
    runApp(const ConfigErrorApp());
  }
}

Troubleshooting & Best Practices

Configuration Best Practices

Use environment variables for all sensitive configuration
Validate configuration before app initialization
Use different credentials for each environment
Never hardcode production credentials in source code
Test configuration changes in development first
If you encounter authentication or network issues, double-check your environment and credentials
Ensure all required parameters are provided during SDK initialization

Next Steps

SDK Reference: Complete API documentation

Change History

Date	Change
2026-02-24	Added route-registration prerequisite note for `Navigator.pushNamed` WebView navigation example.
2026-02-13	Updated `EnvironmentConfig` helper to use `Environment` enum. Fixed `init()` call to use `await`.
2026-02-11	Replaced Bupa-specific URL example with generic `your-client.gofa.app` placeholder.
2026-02-11	Deprecated Basic Authentication section. Removed `basicAuthUser`/`basicAuthPass` from code examples. MSK routes now use Firebase custom tokens.

This guide covers advanced configuration options for the GOFA WebView SDK.

Highlights

Flexible callback configuration for WebView events
Environment-based configuration using helper classes and environment variables
Secure authentication with client credentials and Firebase custom tokens
Customizable navigation URLs for different GOFA services
Support for custom headers
Build-time and runtime configuration via Dart defines
Configuration validation with clear error handling
Troubleshooting tips and configuration best practices

Callback Configuration

The web app posts messages using the postMessage API. The Flutter SDK receives these messages and invokes your updateCallback with the event name and event data.

Basic Event Handler Setup

Basic Event Handler Configuration

final webViewSdkManager = WebViewSdkManager(
  environment: Environment.DEV,
  updateCallback: (String eventName, dynamic eventData) {
    // Handle different event types
    switch (eventName) {
      case 'START_ASSESSMENT':
        // Handle assessment initiation
        _handleAssessmentStart(eventData);
        break;
      case 'FINISH_ASSESSMENT':
        // Handle assessment completion
        _handleAssessmentFinish(eventData);
        break;
      case 'GENERATED_REPORT':
        // Handle report generation
        _handleReportGenerated(eventData);
        break;
      case 'EARLY_QUIT':
        // Handle early exit scenarios
        _handleEarlyQuit(eventData);
        break;
      default:
        print('Unknown event: $eventName');
    }
  },
);

Tip: The updateCallback receives the event name and a data map. You can use this to trigger navigation, analytics, or other business logic in your Flutter app.

Event Details

For specific event types and data structures for different GOFA modules (such as MSK assessments), refer to the respective integration guides:

MSK Integration Guide - Complete MSK event handling

Event Data Structure

Most events follow a consistent data structure pattern:

// Common event data fields
{
  'eventId': 'unique-event-identifier',
  'timestamp': 'iso-date-string',
  'userId': 'user-identifier',
  'moduleType': 'msk|wellness|other',
  // Additional event-specific data
}

Environment Helper Class

Create a helper class for environment-specific configuration:

class EnvironmentConfig {
  static const String _envString = String.fromEnvironment('GOFA_ENVIRONMENT', defaultValue: 'DEV');
  static const String clientId = String.fromEnvironment('GOFA_CLIENT_ID');
  static const String clientSecret = String.fromEnvironment('GOFA_CLIENT_SECRET');
  static const String clientUserId = String.fromEnvironment('GOFA_CLIENT_USER_ID');

  /// Converts the GOFA_ENVIRONMENT string to the SDK enum.
  static Environment get environment {
    switch (_envString.toUpperCase()) {
      case 'PRD': return Environment.PRD;
      case 'UAT': return Environment.UAT;
      default:   return Environment.DEV;
    }
  }

  static bool get isProduction => environment == Environment.PRD;

  static String get baseUrl {
    switch (environment) {
      case Environment.PRD: return 'https://client.gofa.app';
      case Environment.UAT: return 'https://client.uat.gofa.app';
      default: return 'https://client.dev.gofa.app';
    }
  }
}

URL Examples

Route Registration Required

If you navigate with Navigator.pushNamed(..., GofaWebView.routeName, ...), ensure GofaWebView.routeName is registered in your app's MaterialApp.routes first.


Navigator.pushNamed(
  context,
  GofaWebView.routeName,
  arguments: {
    // Example: MSK (Musculoskeletal) services
    'url': 'https://your-client.gofa.app/msk/home',
    'clientId': clientId,
    'locale': const Locale.fromSubtags(
      languageCode: 'zh',
      scriptCode: 'Hant',
    ),
  },
);

Authentication Configuration

Client Credentials

Configure your application's authentication credentials:

const clientId = String.fromEnvironment('GOFA_CLIENT_ID', defaultValue: 'your-client-id');
const clientSecret = String.fromEnvironment('GOFA_CLIENT_SECRET', defaultValue: 'your-client-secret');
const clientUserId = String.fromEnvironment('GOFA_CLIENT_USER_ID', defaultValue: 'unique-user-id');

Basic Authentication (Deprecated)

Deprecated — Removed in v1.1.0

Custom Headers

You can configure custom headers for WebView requests:

// The SDK automatically handles authentication headers
// Custom headers can be added through the initialization process
await webViewSdkManager.init(
  clientId: clientId,
  clientSecret: clientSecret,
  clientUserId: clientUserId,
  environment: EnvironmentConfig.environment,
);

Runtime Configuration

Environment Variables

Set up environment variables for different build configurations:

# Development build
flutter build apk --dart-define=GOFA_ENVIRONMENT=DEV \
                  --dart-define=GOFA_CLIENT_ID=dev-client-id \
                  --dart-define=GOFA_CLIENT_SECRET=dev-secret

# UAT build
flutter build apk --dart-define=GOFA_ENVIRONMENT=UAT \
                  --dart-define=GOFA_CLIENT_ID=uat-client-id \
                  --dart-define=GOFA_CLIENT_SECRET=uat-secret

# Production build
flutter build apk --dart-define=GOFA_ENVIRONMENT=PRD \
                  --dart-define=GOFA_CLIENT_ID=prod-client-id \
                  --dart-define=GOFA_CLIENT_SECRET=prod-secret

Configuration Validation

Validation Function

Create a validation function to ensure proper configuration:

class ConfigValidator {
  static Future<bool> validateConfiguration() async {
    // Check environment
    if (![Environment.DEV, Environment.UAT, Environment.PRD].contains(EnvironmentConfig.environment)) {
      print('❌ Invalid environment: ${EnvironmentConfig.environment}');
      return false;
    }
    // Check required credentials
    if (EnvironmentConfig.clientId.isEmpty) {
      print('❌ CLIENT_ID is required');
      return false;
    }
    if (EnvironmentConfig.clientSecret.isEmpty) {
      print('❌ CLIENT_SECRET is required');
      return false;
    }
    if (EnvironmentConfig.clientUserId.isEmpty) {
      print('❌ CLIENT_USER_ID is required');
      return false;
    }
    // Validate production settings
    if (EnvironmentConfig.isProduction) {
      if (EnvironmentConfig.clientId == 'abc' ||
          EnvironmentConfig.clientSecret == 'abcSecret') {
        print('❌ Cannot use default credentials in production');
        return false;
      }
    }
    print('✅ Configuration validation passed');
    return true;
  }
}

// Use in your app initialization
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  if (await ConfigValidator.validateConfiguration()) {
    runApp(const MyApp());
  } else {
    runApp(const ConfigErrorApp());
  }
}

Troubleshooting & Best Practices

Configuration Best Practices

Use environment variables for all sensitive configuration
Validate configuration before app initialization
Use different credentials for each environment
Never hardcode production credentials in source code
Test configuration changes in development first
If you encounter authentication or network issues, double-check your environment and credentials
Ensure all required parameters are provided during SDK initialization

Next Steps

SDK Reference: Complete API documentation

Change History

Date	Change
2026-02-24	Added route-registration prerequisite note for `Navigator.pushNamed` WebView navigation example.
2026-02-13	Updated `EnvironmentConfig` helper to use `Environment` enum. Fixed `init()` call to use `await`.
2026-02-11	Replaced Bupa-specific URL example with generic `your-client.gofa.app` placeholder.
2026-02-11	Deprecated Basic Authentication section. Removed `basicAuthUser`/`basicAuthPass` from code examples. MSK routes now use Firebase custom tokens.

Advanced Configuration

Highlights

Callback Configuration

Basic Event Handler Setup

Event Data Structure

Environment Helper Class

URL Examples

Authentication Configuration

Client Credentials

Basic Authentication (Deprecated)

Custom Headers

Runtime Configuration

Environment Variables

Configuration Validation

Validation Function

Troubleshooting & Best Practices

Next Steps

Change History

On this page

Advanced Configuration

Highlights

Callback Configuration

Basic Event Handler Setup

Event Data Structure

Environment Helper Class

URL Examples

Authentication Configuration

Client Credentials

Basic Authentication (Deprecated)

Custom Headers

Runtime Configuration

Environment Variables

Configuration Validation

Validation Function

Troubleshooting & Best Practices

Next Steps

Change History

On this page