ussd_flutter_package

A Flutter plugin for handling USSD (Unstructured Supplementary Service Data) requests and responses.

Features

• Send USSD codes.
• Receive and process USSD responses (Android only).
• Send responses to interactive USSD sessions (Android only).
• Check if USSD is supported on the current device.

Platform Support

Note for iOS: Due to platform limitations and security restrictions, direct interaction with USSD sessions (receiving responses or sending interactive responses) is not possible for third-party applications. On iOS, this plugin can only open the dialer with the USSD code, and the user will have to manually interact with the USSD session.

Installation

Add the following to your pubspec.yaml file:

dependencies:
  ussd_flutter_package:
    git:
      url: https://github.com/YOUR_USERNAME/ussd_flutter_package.git # Replace with your repository URL
      ref: main # Or the branch/tag you want to use

Or, if you want to use it directly from your local path during development:

dependencies:
  ussd_flutter_package:
    path: ../ussd_flutter_package # Adjust path as needed

Then run flutter pub get.

Android Setup

Add the following permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.CALL_PHONE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

Usage

import 'package:ussd_flutter_package/ussd_flutter_package.dart';
import 'package:ussd_flutter_package/ussd_service.dart'; // For UssdResponse and UssdSessionState

void main() {
  runApp(MyApp());
}

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

class _MyAppState extends State<MyApp> {
  final UssdService _ussdService = UssdService();
  String _ussdResult = 'No USSD response yet.';

  @override
  void initState() {
    super.initState();
    _ussdService.ussdResponseStream.listen((response) {
      setState(() {
        _ussdResult = 'Message: ${response.message}\nState: ${response.state}';
      });
    }, onError: (error) {
      setState(() {
        _ussdResult = 'Error: ${error.message}';
      });
    });
  }

  Future<void> _sendUssdCode(String ussdCode) async {
    try {
      final response = await _ussdService.sendUssd(ussdCode);
      setState(() {
        _ussdResult = 'Message: ${response.message}\nState: ${response.state}';
      });
    } catch (e) {
      setState(() {
        _ussdResult = 'Error sending USSD: $e';
      });
    }
  }

  Future<void> _sendUssdResponse(String response) async {
    try {
      final ussdResponse = await _ussdService.sendResponse(response);
      setState(() {
        _ussdResult = 'Message: ${ussdResponse.message}\nState: ${ussdResponse.state}';
      });
    } catch (e) {
      setState(() {
        _ussdResult = 'Error sending response: $e';
      });
    }
  }

  Future<void> _checkUssdSupport() async {
    try {
      final isSupported = await _ussdService.isUssdSupported();
      setState(() {
        _ussdResult = 'USSD Supported: $isSupported';
      });
    } catch (e) {
      setState(() {
        _ussdResult = 'Error checking USSD support: $e';
      });
    }
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(
          title: const Text('USSD Example'),
        ),
        body: Center(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              ElevatedButton(
                onPressed: () => _sendUssdCode('*100#'),
                child: const Text('Send *100# (Balance Check)'),
              ),
              ElevatedButton(
                onPressed: () => _sendUssdCode('*123*1#'),
                child: const Text('Send *123*1# (Example Menu)'),
              ),
              ElevatedButton(
                onPressed: () => _sendUssdResponse('1'), // For interactive sessions
                child: const Text('Send Response (e.g., 1)'),
              ),
              ElevatedButton(
                onPressed: _checkUssdSupport,
                child: const Text('Check USSD Support'),
              ),
              SizedBox(height: 20),
              Text(_ussdResult),
            ],
          ),
        ),
      ),
    );
  }
}

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.