QuipuScore SMS Plugin

A Flutter plugin for reading and syncing SMS messages to a backend server on Android devices. This plugin bridges Flutter applications to the reusable SMS SDK Android library published via Maven.

⚠️ IMPORTANT: This plugin uses READ_SMS permission. Ensure you comply with Google Play policies regarding SMS permissions.

Platform Support

Platform	Supported
Android	✅ Yes
iOS	❌ No
Web	❌ No

Minimum Requirements:

• Android API 22+ (Android 5.1 Lollipop)
• Flutter 3.0.0+
• Dart 3.0.0+

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  quipuscore_sms_plugin: ^0.0.1

Then run:

flutter pub get

Android Configuration

The plugin automatically configures necessary permissions, but ensure your app's android/app/build.gradle has the correct SDK versions:

android {
    compileSdkVersion 34

    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 34
    }
}

Usage

1. Import the Plugin

import 'package:quipuscore_sms_plugin/quipuscore_sms_plugin.dart';

2. Initialize the Plugin

Before using any SMS functionality, initialize the plugin with your authentication credentials:

final smsPlugin = SmsPluginFlutter();

try {
  final result = await smsPlugin.initialize(
    InitializeOptions(
      clientId: 'your-client-id',
      token: 'your-api-token',
    ),
  );
  
  if (result.success) {
    print('Initialization successful: ${result.message}');
  }
} on PlatformException catch (e) {
  print('Initialization failed: ${e.message}');
}

Note: The token determines the environment (sandbox or production) automatically.

3. Collect and Sync SMS

try {
  final result = await smsPlugin.collectAndSync(
    CollectAndSyncOptions(
      deviceId: 'unique-device-id',
      userId: 'user-123', // Optional
      identityNumber: 'ID-456', // Optional
      identityType: 'national-id', // Optional
    ),
  );
  
  if (result.success) {
    print('SMS synced: ${result.message}');
  }
} on PlatformException catch (e) {
  if (e.code == 'PERMISSION_DENIED') {
    print('User denied SMS permission');
  } else {
    print('Sync failed: ${e.message}');
  }
}

Permission Handling: The plugin will automatically request READ_SMS permission if not already granted when calling collectAndSync().

4. Link User with Device

Associate a user ID with a device ID on the backend:

try {
  final result = await smsPlugin.linkUserIdWithDevice(
    LinkUserIdWithDeviceOptions(
      userId: 'user-123',
      deviceId: 'unique-device-id',
    ),
  );
  
  if (result.success) {
    print('User linked: ${result.message}');
  }
} on PlatformException catch (e) {
  print('Link failed: ${e.message}');
}

API Reference

Classes

SmsPluginFlutter

Main plugin class for interacting with SMS functionality.

Methods:

• Future<InitializeResult> initialize(InitializeOptions options)

  • Initialize the plugin with authentication credentials
  • Must be called before any other operations

• Future<SyncSmsResult> collectAndSync(CollectAndSyncOptions options)

  • Collect SMS from device and sync to backend

• Future<LinkUserIdWithDeviceResult> linkUserIdWithDevice(LinkUserIdWithDeviceOptions options)

  • Link a user ID with a device ID on the backend

Models

InitializeOptions

InitializeOptions({
  required String clientId,    // Your application identifier
  required String token,       // Authentication token
})

CollectAndSyncOptions

CollectAndSyncOptions({
  required String deviceId,    // Device identifier
  String? userId,              // Optional user identifier
  String? identityNumber,      // Optional identity number
  String? identityType,        // Optional identity type
})

LinkUserIdWithDeviceOptions

LinkUserIdWithDeviceOptions({
  required String userId,      // User identifier
  required String deviceId,    // Device identifier
})

Permissions

The plugin requires the following Android permissions to be added in AndroidManifest.xml:

• READ_SMS - To read SMS messages from the device
• INTERNET - To sync data to the backend server

Development

Running the Example App

1. Navigate to the example directory:

   cd example
   

2. Get dependencies:

   flutter pub get
   

3. Run on an Android device:

   flutter run
   

Project Structure

sms_plugin_flutter/
├── android/                      # Android platform code
│   ├── src/main/
│   │   ├── java/
│   │   │   └── com/quipumarket/sms_plugin/
│   │   │       └── SmsPlugin.java    # Main plugin bridge
│   │   └── AndroidManifest.xml
│   └── build.gradle             # Android build config
├── lib/                         # Dart code
│   ├── src/
│   │   ├── models.dart         # Data models
│   │   └── sms_plugin.dart     # Main plugin class
│   └── sms_plugin_flutter.dart # Public API
├── example/                     # Example Flutter app
│   ├── lib/
│   │   └── main.dart
│   └── android/
└── pubspec.yaml

License

MIT License - See LICENSE file for details

---