SDK Initialization

How to initialize the Upshot.ai Flutter SDK in your application.

Overview

You should initialize the SDK every time the app is launched or app comes to foreground from background. For every initialization you will get authentication status using Method Channel. A session is created every time the SDK is initialized.

There are multiple options that can be set/modified while initializing the SDK based on your application preferences and utilization of various system resources.

Basic Initialization

Initialize the SDK with your app credentials:

import 'package:flutter_upshot_plugin/flutter_upshot_plugin.dart';
import 'package:flutter_upshot_plugin/upshotConstants.dart';

// Initialize SDK in your main.dart or app entry point
void initializeUpshot() {
  Map<dynamic, dynamic> initOptions = {
    UpshotInitOptions.appId: "appId",
    UpshotInitOptions.ownerId: "ownerId",
    UpshotInitOptions.enableDebugLogs: false,
    UpshotInitOptions.enableCrashlogs: true,
    UpshotInitOptions.enableLocation: true
  };

  FlutterUpshotPlugin.initialiseUpshotUsingOptions(initOptions);
}

// Call in your app's entry point
initializeUpshot();

Configuration Options

Below are the list of initialization options and their descriptions:

• AppId: Application ID provided by Upshot.ai (can be viewed on dashboard)
• OwnerId: Account ID provided by Upshot.ai (can be viewed on dashboard)
• EnableLocation: By default, location is disabled. To enable it, set this property to true while initializing. This will help capture device's location details
• EnableCrashlogs: Enabling this option allows Upshot.ai to capture crash logs and send it to the servers. This option is enabled by default
• EnableDebugLogs: Enable debug logs for development purposes

Authentication Status

Listen for authentication status after initialization:

// Authentication status callback
static const _channel = MethodChannel('flutter_upshot_plugin');

UpshotMethodChannel() {
_channel.setMethodCallHandler (_methodCallHandler);
}

Future <dynamic>_methodCallHandler(MethodCall call) async {
    Map data = call.arguments as Map;
    if (call.method == 'upshotAuthenticationStatus ') {
    }
}

Note

Send / Create any user details / token updation or events after initializing the Upshot.ai.

Terminating the SDK

By definition, every open app is a session. Hence, when the app goes to background the session should be terminated. And when the app comes back to the foreground, the session should be reinitialized.

// Terminate the SDK when app goes to background
FlutterUpshotPlugin.terminate();

Every successful authentication creates a new session. A session is terminated only when a call to terminate function/method is made. Repeated calls to initialiseUpshotUsingOptions will terminate the existing session and create a new session.

Complete Example

Here's a complete example of SDK initialization in a Flutter app:

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_upshot_plugin/flutter_upshot_plugin.dart';
import 'package:flutter_upshot_plugin/upshotConstants.dart';

class UpshotManager {
  static const _channel = MethodChannel('flutter_upshot_plugin');

  static void initialize() {
    Map<dynamic, dynamic> initOptions = {
      UpshotInitOptions.appId: "your_app_id",
      UpshotInitOptions.ownerId: "your_owner_id",
      UpshotInitOptions.enableDebugLogs: false,
      UpshotInitOptions.enableCrashlogs: true,
      UpshotInitOptions.enableLocation: true
    };

    FlutterUpshotPlugin.initialiseUpshotUsingOptions(initOptions);
    _setupMethodChannel();
  }

  static void _setupMethodChannel() {
    _channel.setMethodCallHandler((MethodCall call) async {
      switch (call.method) {
        case 'upshotAuthenticationStatus':
          _handleAuthStatus(call.arguments);
          break;
      }
    });
  }

  static void _handleAuthStatus(dynamic arguments) {
    Map<String, dynamic> authStatus = arguments;
    if (authStatus['status'] == 'Success') {
      print('✅ Upshot SDK initialized successfully');
    } else {
      print('❌ Upshot SDK initialization failed: ${authStatus['errorMessage']}');
    }
  }

  static void terminate() {
    FlutterUpshotPlugin.terminate();
  }
}

// In your main.dart
void main() {
  runApp(MyApp());
  UpshotManager.initialize();
}

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        UpshotManager.initialize();
        break;
      case AppLifecycleState.paused:
        UpshotManager.terminate();
        break;
      default:
        break;
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Upshot Flutter Demo',
      home: MyHomePage(),
    );
  }
}

Session Management

Session Creation

A new session is registered every time the SDK is initialized. When the app goes to the background, the session needs to be terminated.

Session Termination

// Terminate the current session
    FlutterUpshotPlugin.terminate();

Important Notes:

• Every successful authentication creates a new session
• Sessions are terminated only when terminate() is called
• Every time initializeUpshot is called, the old session gets terminated and a new session starts
• Avoid multiple duplicate sessions by not initializing the SDK when navigating between screens unless it's a specific business need

App Lifecycle Integration

Foreground Initialization

Initialize the SDK when the app comes to foreground:

// Flutter automatically handles app state changes

// Handle app state changes
@override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    switch (state) {
      case AppLifecycleState.resumed:
        UpshotManager.initialize();
        break;
      case AppLifecycleState.paused:
        UpshotManager.terminate();
        break;
      default:
        break;
    }
  }

Verification

Run Your Application

On Upshot.ai SDK integration success, you can see an active user on the dashboard LiveEvents Section.

Testing Integration

// Test if SDK is properly initialized
const testSDKStatus = () => {
  Upshot.addListener("UpshotAuthStatus", (response) => {
    if (response.status) {
      console.log("✅ SDK is working correctly");
      // You should see this user in the Upshot.ai dashboard
    } else {
      console.error("❌ SDK initialization failed:", response.error);
    }
  });
};

Environment Configuration

Development vs. Production

Use different configurations for development and production:

// Using environment variables or constants
static void initialize() {
 if (__DEV__) {
    return {
      UpshotInitOptions.appId: "DEV_APP_ID",
      UpshotInitOptions.ownerId: "DEV_OWNER_ID",
      UpshotInitOptions.enableDebugLogs: false,
      UpshotInitOptions.enableCrashlogs: true,
      UpshotInitOptions.enableLocation: true


    };
  } else {
    return {
      UpshotInitOptions.appId: "PROD_APP_ID",
      UpshotInitOptions.ownerId: "PROD_OWNER_ID",
      UpshotInitOptions.enableDebugLogs: false,
      UpshotInitOptions.enableCrashlogs: true,
      UpshotInitOptions.enableLocation: true

    };
  }
};

// Initialize with environment-specific config
FlutterUpshotPlugin.initialiseUpshotUsingOptions(initOptions);

Best Practices

1. Initialize early in app lifecycle
2. Always add authentication status listener before initialization
3. Handle app state changes for proper session management
4. Terminate sessions when app goes to background
5. Use environment-specific configurations
6. Avoid multiple initializations during app navigation

Troubleshooting

Common initialization issues and solutions:

Invalid Credentials

• Verify App ID and Owner ID from Upshot.ai dashboard
• Check environment configuration
• Confirm account status on dashboard

Authentication Failures

• Check network connectivity
• Verify API endpoint accessibility
• Review authentication response error messages
• Ensure proper listener setup before initialization

Session Issues

• Avoid multiple simultaneous sessions
• Always terminate sessions on app background
• Check session timeout configurations
• Monitor active sessions on dashboard