feat: update README and iOS integration guide to enhance push notification setup and event handling

Author: pitzcarraldo

README.md

@@ -5,6 +5,7 @@ Clix Flutter SDK is a powerful tool for managing push notifications and user eve
 ## Installation
 
 Add this to your package's `pubspec.yaml` file:
+
 ```yaml
 dependencies:
   clix_flutter: ^0.0.2
@@ -21,6 +22,7 @@ flutter pub get
 - Flutter 3.0.0 or later
 - Dart 2.17.0 or later
 - iOS 14.0+ / Android API 21+
+- Firebase Cloud Messaging
 
 ## Usage
 
@@ -34,19 +36,18 @@ import 'package:firebase_core/firebase_core.dart';
 
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
-  
+
   // Initialize Firebase first
   await Firebase.initializeApp();
-  
+
   // Initialize Clix SDK
   await Clix.initialize(const ClixConfig(
     projectId: 'YOUR_PROJECT_ID',
     apiKey: 'YOUR_API_KEY',
     endpoint: 'https://api.clix.so', // Optional: default is https://api.clix.so
-    logLevel: ClixLogLevel.debug, // Optional: set log level
-    extraHeaders: {}, // Optional: extra headers for API requests
+    logLevel: ClixLogLevel.debug,     // Optional: set log level
   ));
-  
+
   runApp(MyApp());
 }
 ```
@@ -62,7 +63,6 @@ await Clix.setUserProperty('name', 'John Doe');
 await Clix.setUserProperties({
   'age': 25,
   'premium': true,
-  'subscription_plan': 'pro',
 });
 
 // Remove user properties
@@ -73,14 +73,29 @@ await Clix.removeUserProperties(['age', 'premium']);
 await Clix.removeUserId();
 ```
 
+### Event Tracking
+
+```dart
+// Track an event with properties
+await Clix.trackEvent(
+  'signup_completed',
+  properties: {
+    'method': 'email',
+    'discount_applied': true,
+    'trial_days': 14,
+    'completed_at': DateTime.now(),
+  },
+);
+```
+
 ### Device Information
 
 ```dart
 // Get device ID
 final deviceId = await Clix.getDeviceId();
 
 // Get push token
-final pushToken = await Clix.getPushToken();
+final pushToken = await Clix.Notification.getToken();
 ```
 
 ### Logging
@@ -100,94 +115,76 @@ Clix.setLogLevel(ClixLogLevel.debug);
 
 The Clix Flutter SDK automatically handles push notification integration through Firebase Cloud Messaging.
 
-#### Setup Firebase
-
-1. **Add Firebase to your Flutter project**
-   - Follow the [Firebase setup guide](https://firebase.google.com/docs/flutter/setup)
-   - Add `google-services.json` (Android) and `GoogleService-Info.plist` (iOS)
-
-2. **Enable Push Notifications**
-   - For iOS: Enable Push Notifications capability in Xcode
-   - For Android: No additional setup required
-
-3. **Add Firebase dependencies**
-
-```yaml
-dependencies:
-  firebase_core: ^3.6.0
-  firebase_messaging: ^15.1.3
-```
-
-#### Handling Notifications
-
-The SDK automatically handles notification registration and token management. Notifications are processed internally for analytics and tracking.
-
-```dart
-// Notification handling is automatic - no additional code required
-// The SDK will track notification delivery and engagement automatically
-```
-
-## Firebase Setup
-
-### iOS Setup
+#### 1. Firebase Setup
 
+**iOS:**
 1. Add your `GoogleService-Info.plist` to the iOS project in Xcode
 2. Enable Push Notifications capability in your iOS project
 3. Add Background Modes capability and check "Remote notifications"
 
-### Android Setup
-
+**Android:**
 1. Add your `google-services.json` to `android/app/`
-2. Add the Google Services plugin to your `android/build.gradle`:
+2. Firebase configuration is handled automatically by FlutterFire
 
-```gradle
-buildscript {
-    dependencies {
-        classpath 'com.google.gms:google-services:4.3.15'
-    }
-}
-```
+#### 2. Configure Notification Handlers
 
-3. Apply the plugin in `android/app/build.gradle`:
+Register handlers for push notification events:
 
-```gradle
-apply plugin: 'com.google.gms.google-services'
-```
+```dart
+void main() async {
+  WidgetsFlutterBinding.ensureInitialized();
 
-## Configuration Options
+  await Firebase.initializeApp();
+  await Clix.initialize(const ClixConfig(
+    projectId: 'YOUR_PROJECT_ID',
+    apiKey: 'YOUR_API_KEY',
+  ));
 
-### ClixConfig
+  // Register notification handlers
+  Clix.Notification.onMessage((notificationData) async {
+    // Return true to display the notification, false to suppress it
+    return true;
+  });
+
+  Clix.Notification.onBackgroundMessage((notificationData) {
+    // Handle background notification
+    print('Background notification received: $notificationData');
+  });
+
+  Clix.Notification.onNotificationOpened((notificationData) {
+    // Custom routing (called when user taps notification)
+    final clixData = notificationData['clix'] as Map<String, dynamic>?;
+    final landingURL = clixData?['landing_url'] as String?;
+    if (landingURL != null) {
+      // Handle custom routing
+    }
+  });
 
-- `projectId` (required): Your Clix project ID
-- `apiKey` (required): Your Clix API key  
-- `endpoint`: API endpoint (default: 'https://api.clix.so')
-- `logLevel`: Logging level (default: ClixLogLevel.error)
-- `extraHeaders`: Additional HTTP headers for API requests
+  Clix.Notification.onFcmTokenError((error) {
+    print('FCM token error: $error');
+  });
 
-### ClixLogLevel
+  runApp(MyApp());
+}
+```
 
-- `verbose`: All logs including detailed debugging
-- `debug`: Debug information and above
-- `info`: General information and above
-- `warning`: Warning messages and above
-- `error`: Error messages only
-- `none`: No logging
+**Important:** All `Clix.Notification` methods must be called **after** `Clix.initialize()`.
 
-## Sample App
+##### About `notificationData`
 
-A comprehensive sample app is provided in the `samples/basic_app` directory. The sample demonstrates:
+- The `notificationData` map is the full FCM payload as delivered to the device
+- Every Clix notification callback (`onMessage`, `onBackgroundMessage`, `onNotificationOpened`) passes this map through untouched
+- `notificationData['clix']` holds the Clix metadata JSON, while all other keys represent app-specific data
 
-- Basic Clix SDK integration
-- Push notification handling with Firebase
-- User property management
-- Device information display
+#### 3. Token Management
 
-To run the sample:
+```dart
+// Get current FCM token
+final token = await Clix.Notification.getToken();
 
-1. Navigate to `samples/basic_app`
-2. Follow the Firebase setup instructions in `FIREBASE_SETUP.md`
-3. Update `lib/clix_info.dart` with your project details
-4. Run the app: `flutter run`
+// Delete FCM token
+await Clix.Notification.deleteToken();
+```
 
 ## Error Handling
 
@@ -205,62 +202,58 @@ try {
 
 The SDK is thread-safe and all operations can be called from any isolate. Async operations will automatically wait for SDK initialization to complete.
 
-## Advanced Features
+## Troubleshooting
 
-### Manual Event Tracking
+### Push Notifications Not Working
 
-While the SDK automatically tracks notification events, you can also track custom events:
+If push notifications aren't working, verify:
 
-```dart
-// Custom event tracking methods would be implemented here
-// Currently handled automatically by the SDK
-```
+1. ✅ Firebase is initialized before Clix SDK
+2. ✅ `google-services.json` (Android) and `GoogleService-Info.plist` (iOS) are added
+3. ✅ Push Notifications capability is enabled (iOS)
+4. ✅ Testing on a real device (push notifications don't work on iOS simulator)
+5. ✅ Debug logs show FCM token registration messages
 
-### Custom Properties
+### FCM Token Errors
 
-User properties support various data types:
+If you're experiencing FCM token registration failures, use the error handler:
 
 ```dart
-await Clix.setUserProperties({
-  'name': 'John Doe',           // String
-  'age': 25,                    // Number
-  'premium': true,              // Boolean
-  'tags': ['flutter', 'mobile'], // Array
-  'metadata': {                 // Object
-    'source': 'mobile_app',
-    'version': '1.0.0',
-  },
+Clix.Notification.onFcmTokenError((error) {
+  print('FCM token error: $error');
+  // Common causes:
+  // - Missing or invalid google-services.json/GoogleService-Info.plist
+  // - Network connectivity issues
+  // - Firebase service errors
 });
 ```
 
-## Platform-Specific Considerations
-
-### iOS
+### Getting Help
 
-- Requires iOS 14.0 or later
-- Push notifications require user permission
-- Background processing is automatically handled
+If you continue to experience issues:
 
-### Android
+1. Enable debug logging (`ClixLogLevel.debug`)
+2. Check console for Clix log messages
+3. Verify your device appears in the Clix console Users page
+4. Check if `push_token` field is populated for your device
+5. Create an issue on [GitHub](https://github.com/clix-so/clix-flutter-sdk/issues) with logs and configuration details
 
-- Requires Android API level 21 or later
-- Notification channels are automatically managed
-- Background processing follows Android guidelines
+## Sample App
 
-## Performance
+A comprehensive sample app is provided in the `samples/basic_app` directory. The sample demonstrates:
 
-- Lightweight initialization
-- Efficient background processing
-- Minimal memory footprint
-- Optimized network requests
+- Basic Clix SDK integration
+- Push notification handling with Firebase
+- User property management
+- Event tracking
+- Device information display
 
-## Privacy
+To run the sample:
 
-The SDK respects user privacy:
-- Only collects necessary device information
-- User data is handled according to your privacy policy
-- Push tokens are managed securely
-- No personal data is collected without consent
+1. Navigate to `samples/basic_app`
+2. Follow the Firebase setup instructions in `FIREBASE_SETUP.md`
+3. Update `lib/clix_configuration.dart` with your project details
+4. Run the app: `flutter run`
 
 ## License
 
@@ -273,10 +266,3 @@ See the full release history and changes in the [CHANGELOG.md](CHANGELOG.md) fil
 ## Contributing
 
 We welcome contributions! Please read the [CONTRIBUTING.md](CONTRIBUTING.md) guide before submitting issues or pull requests.
-
-## Support
-
-For support and questions:
-- Check the sample app for implementation examples
-- Review the API documentation
-- Contact support through your Clix dashboard