sms.ist Flutter SDK #

Official Flutter SDK for sms.ist - Global push notification service without Firebase configuration files.

Features #

• No Firebase Configuration Files - No need for google-services.json or GoogleService-Info.plist
• OneSignal-like Experience - Just initialize with your API key and you're ready
• Centralized Management - Manage all your apps from sms.ist dashboard
• Cross-Platform - Works on both Android and iOS
• Easy Integration - Simple 3-line setup
• Modern Architecture - Uses Firebase HTTP v1 API (future-proof)

Installation #

Add to your pubspec.yaml:

dependencies:
  smsist_flutter: ^0.1.0

Run:

flutter pub get

Quick Start #

1. Initialize SDK #

In your main.dart:

import 'package:smsist_flutter/smsist_flutter.dart';

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

  // Initialize sms.ist SDK
  await SmsIst.init(
    apiKey: 'your-api-key-from-dashboard',
    enableLogs: true, // Optional: enable debug logs
  );

  runApp(MyApp());
}

2. Listen to Notifications #

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

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

    // Listen to notifications
    SmsIst.onNotificationReceived.listen((notification) {
      print('📩 Notification received:');
      print('Title: ${notification.title}');
      print('Body: ${notification.body}');
      print('Data: ${notification.data}');
    });
  }

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

3. Request Permissions (iOS) #

On iOS, you need to request notification permissions:

Future<void> requestPermissions() async {
  final granted = await SmsIst.requestPermissions();

  if (granted) {
    print('✅ Notification permissions granted');
  } else {
    print('❌ Notification permissions denied');
  }
}

How It Works #

Unlike traditional Firebase integration that requires configuration files, sms.ist uses runtime Firebase configuration injection:

1. Backend Provides Config: Your API key is used to fetch Firebase configuration from sms.ist API
2. Dynamic Initialization: Firebase SDK is initialized at runtime with the fetched configuration
3. No Files Needed: No google-services.json or GoogleService-Info.plist required
4. Centralized Management: All apps share the same Firebase project managed by sms.ist

Platform Setup #

Android #

No additional setup required! The SDK handles everything automatically.

iOS #

Add the following to your ios/Runner/AppDelegate.swift:

import UIKit
import Flutter
import FirebaseCore
import FirebaseMessaging

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    // Request notification permissions
    if #available(iOS 10.0, *) {
      UNUserNotificationCenter.current().delegate = self
    }

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }

  // Handle APNs token registration
  override func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    Messaging.messaging().apnsToken = deviceToken
  }
}

API Reference #

SmsIst #

Main SDK class.

static Future<void> init({required String apiKey, String? apiBaseUrl, bool enableLogs = false})

Initialize the SDK.

Parameters:

• apiKey (required): Your API key from sms.ist dashboard
• apiBaseUrl (optional): Custom API base URL (defaults to https://api.sms.ist)
• enableLogs (optional): Enable debug logging (defaults to false)

Example:

await SmsIst.init(
  apiKey: 'your-api-key',
  enableLogs: true,
);

static Stream<SmsIstNotification> get onNotificationReceived

Stream of incoming notifications.

Example:

SmsIst.onNotificationReceived.listen((notification) {
  print('Received: ${notification.title}');
});

static Future<bool> requestPermissions()

Request notification permissions (iOS only, always returns true on Android).

Returns: true if granted, false otherwise.

Example:

final granted = await SmsIst.requestPermissions();

static Future<bool> checkPermissions()

Check if notification permissions are granted.

Returns: true if granted, false otherwise.

Example:

final granted = await SmsIst.checkPermissions();

static Future<String?> refreshToken()

Manually refresh the FCM device token.

Returns: New device token.

Example:

final token = await SmsIst.refreshToken();

static Future<void> unregister()

Unregister device from sms.ist (e.g., on user logout).

Example:

await SmsIst.unregister();

static bool get isInitialized

Check if SDK is initialized.

Example:

if (SmsIst.isInitialized) {
  print('SDK is ready');
}

static String? get deviceToken

Get current device token.

Example:

print('Device token: ${SmsIst.deviceToken}');

SmsIstNotification #

Notification model.

Properties:

• String title: Notification title
• String body: Notification body
• Map<String, dynamic>? data: Custom data payload
• DateTime receivedAt: Timestamp when notification was received

Example:

SmsIst.onNotificationReceived.listen((notification) {
  print('Title: ${notification.title}');
  print('Body: ${notification.body}');
  print('Data: ${notification.data}');
  print('Received at: ${notification.receivedAt}');
});

Getting Your API Key #

1. Go to sms.ist dashboard
2. Create an account or log in
3. Create a new app
4. Copy your API key
5. Use it in SmsIst.init()

Backend Setup (For Platform Owners) #

If you're running your own sms.ist instance, make sure to:

1. Add Firebase Service Account JSON to backend/config/firebase-service-account.json
2. Set environment variables in .env:

   FIREBASE_WEB_API_KEY=your-web-api-key
   FIREBASE_APP_ID=your-app-id
   

3. Restart backend: docker-compose restart api

See FIREBASE_SETUP.md for detailed setup instructions.

Troubleshooting #

Android #

Issue: Build fails with Firebase dependency error

Solution: Make sure you're using:

• Android SDK 34 or higher
• Kotlin 1.9.0 or higher
• Gradle 8.1.0 or higher

iOS #

Issue: Notifications not received on iOS

Solution:

1. Make sure you've requested permissions with SmsIst.requestPermissions()
2. Check that APNs is properly configured in Firebase Console
3. Verify that AppDelegate.swift is properly set up (see Platform Setup section)

Issue: Build fails with Firebase pod error

Solution:

cd ios
rm -rf Pods Podfile.lock
pod install
cd ..
flutter clean
flutter build ios

Example App #

See the example/ directory for a complete working example.

Support #

• Dashboard: sms.ist
• Issues: GitHub Issues
• Website: sms.ist

License #

MIT License - see LICENSE file for details

Made with ❤️ by sms.ist team