PushFire Flutter SDK #

A Flutter SDK for integrating with the PushFire push notification service. This SDK provides easy-to-use APIs for device registration, subscriber management, and tag operations.

Features #

• 🚀 Automatic Device Registration: Seamlessly registers devices with FCM tokens
• 👤 Subscriber Management: Login, update, and logout subscribers
• 🏷️ Tag Management: Add, update, and remove subscriber tags
• 📱 Cross-Platform: Works on both iOS and Android
• 🔧 Configurable: Customizable API endpoints and settings
• 📊 Logging: Built-in logging for debugging
• 🔄 Event Streams: Real-time updates via streams
• 🛡️ Error Handling: Comprehensive exception handling

Installation #

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

dependencies:
  pushfire_sdk: ^1.0.0

Then run:

flutter pub get

Setup #

1. Firebase Setup #

This SDK uses Firebase Cloud Messaging (FCM) for push notifications. You need to:

1. Create a Firebase project at Firebase Console
2. Add your Android/iOS app to the project
3. Install FlutterFire CLI and configure Firebase:

   dart pub global activate flutterfire_cli
   flutterfire configure
   

4. This will generate firebase_options.dart file with your Firebase configuration
5. Download and add the configuration files:
   • google-services.json for Android (place in android/app/)
   • GoogleService-Info.plist for iOS (place in ios/Runner/)
6. Follow the FlutterFire setup guide for platform-specific configuration

2. Platform Configuration #

Android

Add the following to your android/app/build.gradle:

dependencies {
    implementation 'com.google.firebase:firebase-messaging:23.0.0'
}

iOS

Enable push notifications in your iOS project:

1. Open ios/Runner.xcworkspace in Xcode
2. Select your project target
3. Go to "Signing & Capabilities"
4. Add "Push Notifications" capability
5. Add "Background Modes" capability and enable "Background processing" and "Remote notifications"

Usage #

1. Initialize the SDK #

Initialize the SDK in your app's main() function:

import 'package:pushfire_sdk/pushfire_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  // Initialize PushFire SDK
  await PushFireSDK.initialize(
    PushFireConfig(
      apiKey: 'your-api-key-here',
      baseUrl: 'https://api.pushfire.com', // Optional: defaults to production
      enableLogging: true, // Optional: enable for debugging
      timeoutSeconds: 30, // Optional: request timeout
    ),
  );
  
  runApp(MyApp());
}

2. Subscriber Management #

Login/Register a Subscriber

try {
  final subscriber = await PushFireSDK.instance.loginSubscriber(
    externalId: 'user123', // Your user ID
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1234567890',
  );
  
  print('Subscriber logged in: ${subscriber.id}');
} catch (e) {
  print('Login failed: $e');
}

Update Subscriber

try {
  final updatedSubscriber = await PushFireSDK.instance.updateSubscriber(
    name: 'John Smith',
    email: 'johnsmith@example.com',
  );
  
  print('Subscriber updated: ${updatedSubscriber.name}');
} catch (e) {
  print('Update failed: $e');
}

Logout Subscriber

try {
  await PushFireSDK.instance.logoutSubscriber();
  print('Subscriber logged out');
} catch (e) {
  print('Logout failed: $e');
}

Check Subscriber Status

// Check if subscriber is logged in
final isLoggedIn = await PushFireSDK.instance.isSubscriberLoggedIn();

// Get current subscriber
final subscriber = await PushFireSDK.instance.getCurrentSubscriber();
if (subscriber != null) {
  print('Current subscriber: ${subscriber.name}');
}

3. Tag Management #

Add Tags

// Add single tag
try {
  final tag = await PushFireSDK.instance.addTag('user_type', 'premium');
  print('Tag added: ${tag.tagId} = ${tag.value}');
} catch (e) {
  print('Failed to add tag: $e');
}

// Add multiple tags
try {
  final tags = await PushFireSDK.instance.addTags({
    'user_type': 'premium',
    'subscription_plan': 'yearly',
    'region': 'us-west',
  });
  
  print('Added ${tags.length} tags');
} catch (e) {
  print('Failed to add tags: $e');
}

Update Tags

// Update single tag
try {
  final tag = await PushFireSDK.instance.updateTag('user_type', 'enterprise');
  print('Tag updated: ${tag.tagId} = ${tag.value}');
} catch (e) {
  print('Failed to update tag: $e');
}

// Update multiple tags
try {
  final tags = await PushFireSDK.instance.updateTags({
    'user_type': 'enterprise',
    'subscription_plan': 'monthly',
  });
  
  print('Updated ${tags.length} tags');
} catch (e) {
  print('Failed to update tags: $e');
}

Remove Tags

// Remove single tag
try {
  await PushFireSDK.instance.removeTag('user_type');
  print('Tag removed');
} catch (e) {
  print('Failed to remove tag: $e');
}

// Remove multiple tags
try {
  await PushFireSDK.instance.removeTags(['user_type', 'region']);
  print('Tags removed');
} catch (e) {
  print('Failed to remove tags: $e');
}

4. Device Information #

// Get current device
final device = PushFireSDK.instance.currentDevice;
if (device != null) {
  print('Device ID: ${device.id}');
  print('FCM Token: ${device.fcmToken}');
  print('OS: ${device.os} ${device.osVersion}');
}

// Get device ID
final deviceId = await PushFireSDK.instance.getDeviceId();
print('Device ID: $deviceId');

// Get subscriber ID
final subscriberId = await PushFireSDK.instance.getSubscriberId();
print('Subscriber ID: $subscriberId');

5. Event Streams #

Listen to real-time events:

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

class _MyAppState extends State<MyApp> {
  late StreamSubscription _deviceSubscription;
  late StreamSubscription _subscriberSubscription;
  late StreamSubscription _fcmSubscription;
  
  @override
  void initState() {
    super.initState();
    _setupEventListeners();
  }
  
  void _setupEventListeners() {
    // Listen to device registration events
    _deviceSubscription = PushFireSDK.instance.onDeviceRegistered.listen(
      (device) {
        print('Device registered: ${device.id}');
      },
    );
    
    // Listen to subscriber login events
    _subscriberSubscription = PushFireSDK.instance.onSubscriberLoggedIn.listen(
      (subscriber) {
        print('Subscriber logged in: ${subscriber.name}');
      },
    );
    
    // Listen to FCM token refresh events
    _fcmSubscription = PushFireSDK.instance.onFcmTokenRefresh.listen(
      (token) {
        print('FCM token refreshed: $token');
      },
    );
  }
  
  @override
  void dispose() {
    _deviceSubscription.cancel();
    _subscriberSubscription.cancel();
    _fcmSubscription.cancel();
    super.dispose();
  }
  
  // ... rest of your widget
}

6. Error Handling #

The SDK provides specific exception types for different error scenarios:

try {
  await PushFireSDK.instance.loginSubscriber(externalId: 'user123');
} on PushFireNotInitializedException {
  print('SDK not initialized');
} on PushFireSubscriberException catch (e) {
  print('Subscriber error: ${e.message}');
} on PushFireApiException catch (e) {
  print('API error: ${e.message} (${e.statusCode})');
} on PushFireNetworkException catch (e) {
  print('Network error: ${e.message}');
} catch (e) {
  print('Unknown error: $e');
}

7. Advanced Usage #

Reset SDK

// Reset SDK and clear all data
await PushFireSDK.instance.reset();

Dispose SDK

// Dispose SDK resources (call when app is shutting down)
PushFireSDK.dispose();

Check Initialization Status

if (PushFireSDK.isInitialized) {
  print('SDK is ready to use');
} else {
  print('SDK needs to be initialized');
}

Configuration Options #

PushFireConfig #

Error Types #

• PushFireException - Base exception class
• PushFireApiException - API-related errors
• PushFireNotInitializedException - SDK not initialized
• PushFireConfigurationException - Configuration errors
• PushFireDeviceException - Device registration errors
• PushFireSubscriberException - Subscriber operation errors
• PushFireTagException - Tag operation errors
• PushFireNetworkException - Network connectivity errors

Best Practices #

1. Initialize Early: Call PushFireSDK.initialize() as early as possible in your app lifecycle
2. Handle Errors: Always wrap SDK calls in try-catch blocks
3. Check Status: Use isSubscriberLoggedIn() before performing subscriber operations
4. Listen to Events: Use event streams to react to SDK state changes
5. Dispose Resources: Call PushFireSDK.dispose() when your app shuts down
6. Enable Logging: Use enableLogging: true during development for debugging

Troubleshooting #

Common Issues #

1. SDK Not Initialized

   • Ensure you call PushFireSDK.initialize() before using any other methods
   • Check that initialization completes successfully

2. Device Registration Fails

   • Verify Firebase setup is correct
   • Check that FCM is properly configured
   • Ensure device has internet connectivity

3. API Errors

   • Verify your API key is correct
   • Check that the base URL is accessible
   • Ensure your PushFire account is active

4. Subscriber Operations Fail

   • Make sure a subscriber is logged in before performing operations
   • Verify the external ID is valid

Debug Logging #

Enable logging to see detailed information about SDK operations:

await PushFireSDK.initialize(
  PushFireConfig(
    apiKey: 'your-api-key',
    enableLogging: true, // Enable this for debugging
  ),
);

Support #

For issues and questions:

1. Check the troubleshooting section
2. Review the API documentation
3. Contact support at support@pushfire.com

License #

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