SMS.IST Flutter SDK

Official Flutter SDK for SMS.IST Push Notification Platform.

Send push notifications to iOS and Android devices without managing Firebase/APNs configurations. All configurations are managed securely on the SMS.IST backend, and fetched at runtime.

Features

  • No Configuration Files Required: No need for google-services.json or GoogleService-Info.plist
  • Runtime Configuration: Firebase/APNs configs fetched securely from your SMS.IST dashboard
  • Auto Device Registration: Automatic device token registration with your backend
  • Cross-Platform: Works seamlessly on iOS and Android
  • Notification Callbacks: Listen to foreground and background notifications
  • Easy Integration: Simple 3-step setup
  • Type-Safe API: Full Dart type safety with detailed documentation

Installation

Add smsist_flutter to your pubspec.yaml:

dependencies:
  smsist_flutter: ^1.0.0

Run:

flutter pub get

Setup

1. Configure SMS.IST Dashboard

Before using the SDK, you need to:

  1. Create an account at dashboard.sms.ist
  2. Create a new app
  3. Upload your Firebase Service Account JSON
  4. (For iOS) Upload your APNs P8 key

That's it! No need to add these files to your Flutter project.

2. Initialize SDK

Initialize the SDK in your main.dart:

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize SMS.IST SDK
  await SmsistFlutter.initialize(
    apiKey: 'your_api_key_here', // Get from dashboard
    baseUrl: 'https://api.sms.ist',
    debug: true, // Enable debug logs
  );

  runApp(MyApp());
}

3. Listen to Notifications

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

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _setupNotificationListeners();
  }

  void _setupNotificationListeners() {
    // Foreground notifications
    SmsistFlutter.onMessage.listen((notification) {
      print('Received: ${notification.title}');
      print('Body: ${notification.body}');
      print('Data: ${notification.data}');

      // Show in-app alert, update UI, etc.
    });

    // Notification tap (background/terminated)
    SmsistFlutter.onMessageOpenedApp.listen((notification) {
      print('Notification tapped: ${notification.title}');

      // Navigate to specific screen based on notification data
      if (notification.deepLink != null) {
        // Handle deep link
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: HomePage(),
    );
  }
}

Configuration Options

await SmsistFlutter.initialize(
  // Required
  apiKey: 'smsist_prod_xxxxx', // Your app's API key from dashboard

  // Optional
  baseUrl: 'https://api.sms.ist', // API base URL (default)
  debug: false, // Enable debug logging (default: false)
  autoRegister: true, // Auto-register device token (default: true)
  autoRequestPermissions: true, // Auto-request notification permissions (default: true)
  defaultChannelName: 'Push Notifications', // Android channel name
  defaultChannelDescription: 'Receive important updates', // Android channel description
);

API Reference

SmsistFlutter

Main SDK class.

Static Methods

initialize()

Initialize the SDK. Must be called before any other SDK methods.

await SmsistFlutter.initialize(
  apiKey: 'your_api_key',
);

Parameters:

  • apiKey (String, required): Your SMS.IST API key
  • baseUrl (String, optional): API base URL
  • debug (bool, optional): Enable debug logging
  • autoRegister (bool, optional): Auto-register device token
  • autoRequestPermissions (bool, optional): Auto-request permissions
  • defaultChannelName (String, optional): Android notification channel name
  • defaultChannelDescription (String, optional): Android notification channel description

Throws:

  • InitializationException: If initialization fails
  • InvalidApiKeyException: If API key is invalid
  • NetworkException: If unable to connect to backend
requestPermissions()

Manually request notification permissions.

bool granted = await SmsistFlutter.requestPermissions();

Returns: bool - true if permission granted

registerDevice()

Manually register device token.

await SmsistFlutter.registerDevice();

Useful if autoRegister was set to false during initialization.

getDeviceToken()

Get the current device FCM token.

String? token = await SmsistFlutter.getDeviceToken();
print('Device token: $token');

Returns: String? - Device token or null if not registered

setUserProperties()

Set custom user properties to be associated with the device.

await SmsistFlutter.setUserProperties({
  'user_id': '12345',
  'email': 'user@example.com',
  'plan': 'premium',
});

Parameters:

  • properties (Map<String, dynamic>): Custom user properties
subscribeToTopic()

Subscribe to a Firebase Cloud Messaging topic.

await SmsistFlutter.subscribeToTopic('news');

Parameters:

  • topic (String): Topic name
unsubscribeFromTopic()

Unsubscribe from a topic.

await SmsistFlutter.unsubscribeFromTopic('news');

Parameters:

  • topic (String): Topic name

Static Properties

onMessage

Stream of notifications received while app is in foreground.

SmsistFlutter.onMessage.listen((notification) {
  // Handle foreground notification
});

Returns: Stream<SmsistNotification>

onMessageOpenedApp

Stream of notifications that opened the app (from background/terminated state).

SmsistFlutter.onMessageOpenedApp.listen((notification) {
  // Handle notification tap
  // Navigate to relevant screen
});

Returns: Stream<SmsistNotification>

isInitialized

Check if SDK is initialized.

if (SmsistFlutter.isInitialized) {
  // SDK is ready
}

Returns: bool

deviceToken

Get the current device token.

String? token = SmsistFlutter.deviceToken;

Returns: String?

SmsistNotification

Represents a push notification.

Properties

  • title (String): Notification title
  • body (String): Notification body/message
  • data (Map<String, dynamic>): Custom data payload
  • notificationId (String?): Notification ID
  • imageUrl (String?): Image URL (if provided)
  • deepLink (String?): Deep link URL (if provided)
  • sound (String?): Sound to play
  • badge (int?): Badge count (iOS only)
  • priority (String?): Priority (high/normal)
  • channelId (String?): Channel ID (Android only)

Methods

// Convert to Map
Map<String, dynamic> map = notification.toMap();

// Create from Map
SmsistNotification notification = SmsistNotification.fromMap(map);

// String representation
String str = notification.toString();

Exceptions

SmsistException

Base exception class for all SDK exceptions.

try {
  await SmsistFlutter.initialize(apiKey: 'invalid');
} catch (e) {
  if (e is SmsistException) {
    print('Error: ${e.message}');
    print('Code: ${e.code}');
  }
}

InitializationException

Thrown when SDK initialization fails.

InvalidApiKeyException

Thrown when API key is invalid or malformed.

NetworkException

Thrown when network requests fail.

RegistrationException

Thrown when device registration fails.

PermissionDeniedException

Thrown when notification permission is denied.

Platform-Specific Setup

Android

No additional setup required! The SDK handles everything automatically.

iOS

  1. Add the following to your ios/Runner/Info.plist:
<key>UIBackgroundModes</key>
<array>
  <string>remote-notification</string>
</array>
  1. Enable Push Notifications capability in Xcode:
    • Open ios/Runner.xcworkspace
    • Select Runner target
    • Go to "Signing & Capabilities"
    • Click "+ Capability"
    • Add "Push Notifications"

Testing

Send Test Notification

  1. Go to your app dashboard at dashboard.sms.ist
  2. Navigate to your app
  3. Click "Send Test Notification"
  4. Select a device from the list
  5. Enter title and message
  6. Click "Send"

Send via API

curl -X POST https://api.sms.ist/api/notifications/send \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your_api_key",
    "device_token": "device_fcm_token",
    "title": "Hello from SMS.IST",
    "body": "This is a test notification",
    "data": {
      "screen": "home",
      "user_id": "123"
    }
  }'

Troubleshooting

Notifications not received

  1. Check API key: Ensure your API key is correct
  2. Check Firebase config: Verify Firebase config is uploaded in dashboard
  3. Check device registration: Call getDeviceToken() to verify registration
  4. Check permissions: Ensure notification permissions are granted
  5. Enable debug logging: Set debug: true during initialization

iOS specific issues

  1. No permission prompt: Enable autoRequestPermissions: true
  2. Background notifications not working: Check Info.plist has remote-notification background mode
  3. Push capability: Ensure Push Notifications capability is enabled in Xcode

Android specific issues

  1. Notifications not showing: Check if app is in battery optimization whitelist
  2. Custom sound not working: Ensure sound file is in res/raw/ directory

Advanced Usage

SmsistFlutter.onMessageOpenedApp.listen((notification) {
  final deepLink = notification.deepLink;
  if (deepLink != null) {
    // Parse deep link and navigate
    if (deepLink.contains('/product/')) {
      final productId = deepLink.split('/').last;
      Navigator.push(
        context,
        MaterialPageRoute(
          builder: (context) => ProductPage(productId),
        ),
      );
    }
  }
});

User Segmentation

// Set user properties for targeting
await SmsistFlutter.setUserProperties({
  'user_id': user.id,
  'email': user.email,
  'plan': user.subscriptionPlan,
  'country': user.country,
  'language': user.preferredLanguage,
});

// Subscribe to topics
await SmsistFlutter.subscribeToTopic('news');
await SmsistFlutter.subscribeToTopic('promotions');
if (user.isPremium) {
  await SmsistFlutter.subscribeToTopic('premium');
}

Notification Analytics

SmsistFlutter.onMessage.listen((notification) {
  // Log notification received event
  analytics.logEvent(
    name: 'notification_received',
    parameters: {
      'notification_id': notification.notificationId,
      'title': notification.title,
    },
  );
});

SmsistFlutter.onMessageOpenedApp.listen((notification) {
  // Log notification opened event
  analytics.logEvent(
    name: 'notification_opened',
    parameters: {
      'notification_id': notification.notificationId,
      'title': notification.title,
    },
  );
});

Example App

Check out the example directory for a complete working example.

cd example
flutter run

Comparison with Standard Firebase Setup

Traditional Firebase Setup

❌ Download google-services.json
❌ Add to android/app/
❌ Download GoogleService-Info.plist
❌ Add to ios/Runner/
❌ Configure build.gradle
❌ Update Info.plist
❌ Manual token registration
❌ Manage configs in version control

With SMS.IST Flutter SDK

✅ One-line initialization
✅ No config files needed
✅ Auto device registration
✅ Secure config management
✅ Easy updates via dashboard
✅ Multi-app support
✅ Built-in analytics

Security

  • All Firebase/APNs configurations are encrypted at rest (AES-256-GCM)
  • Configurations are fetched over HTTPS
  • API keys are scoped to specific apps
  • Device tokens are stored securely
  • No sensitive data in your app binary

Support

License

MIT License. See LICENSE for details.

Credits

Developed and maintained by SMS.IST

Made with ❤️ for Flutter developers

Libraries

smsist_flutter
SMS.IST Flutter SDK