omikit-plugin 3.3.7 → 3.3.8

package/README.md

@@ -570,6 +570,7 @@ We support 2 environments. So you need set correct key in Appdelegate.
 ```
 -Android:
 + PERMISSIONS.ANDROID.RECORD_AUDIO
++ PERMISSIONS.ANDROID.POST_NOTIFICATIONS
 + PERMISSIONS.ANDROID.CALL_PHONE
 + PERMISSIONS.ANDROID.CAMERA; (if you want to make Video calls)
 
@@ -579,60 +580,34 @@ We support 2 environments. So you need set correct key in Appdelegate.
 
 ```
 
-### 🔥 **Android 15+ Permission Management**
+### 🔥 **Android Permission Management**
 
-**📌 For Android 15+ (SDK 35+), additional permissions are required:**
+**📌 For Android (SDK), additional permissions are required:**
+
+🔥 Notes:
+	
+  •	POST_NOTIFICATIONS and RECORD_AUDIO must be requested at runtime in your code.
+	
+  •	FOREGROUND_SERVICE* permissions only need to be declared in the manifest; Android will enforce them automatically when you call startForegroundService().
 
 ```xml
-<!-- Required in AndroidManifest.xml -->
+<!-- Runtime permissions -->
 <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>
+<uses-permission android:name="android.permission.RECORD_AUDIO"/>
+
+<!-- Foreground service permissions (manifest only, no runtime request needed) -->
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>
 <uses-permission android:name="android.permission.FOREGROUND_SERVICE_PHONE_CALL"/>
-```
-
-**📌 Built-in Permission Functions:**
-
-✅ **checkPermissionStatus()** - Check current permission status:
-```javascript
-import { checkPermissionStatus } from 'omikit-plugin';
-
-const permissionStatus = await checkPermissionStatus();
-console.log(permissionStatus);
-// Output: { essentialGranted: [...], essentialMissing: [...], canMakeVoipCalls: true/false }
-```
-
-✅ **checkAndRequestPermissions()** - Request all necessary permissions:
-```javascript
-import { checkAndRequestPermissions } from 'omikit-plugin';
-
-const isVideo = true; // Set to true if video call permissions needed
-const permissionsGranted = await checkAndRequestPermissions(isVideo);
-if (permissionsGranted) {
-  console.log('All permissions granted!');
-}
-```
-
-✅ **requestPermissionsByCodes()** - Request specific permissions by error codes:
-```javascript
-import { requestPermissionsByCodes } from 'omikit-plugin';
-
-// Request specific permissions based on error codes from OmiSDK
-const codes = [450, 451, 452]; // Permission error codes
-const result = await requestPermissionsByCodes(codes);
-
-/* 
-Permission Code Mapping:
-- 450: RECORD_AUDIO permission (Android 14+)
-- 451: FOREGROUND_SERVICE permissions (Android 14+) 
-- 452: POST_NOTIFICATIONS permission (Android 13+)
-*/
-```
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" tools:node="remove" /> 
 
-**📌 System Alert Window Permission:**
-```javascript
-import { requestSystemAlertWindowPermission } from 'omikit-plugin';
+<service 
+    android:name="net.gotev.sipservice.SipService" 
+    android:foregroundServiceType="phoneCall|microphone" 
+    tools:replace="android:foregroundServiceType" 
+    android:exported="false" 
+/>
 
-const canDrawOverlays = await requestSystemAlertWindowPermission();
 ```
 
 - ✅ Set up <a href="https://rnfirebase.io/messaging/usage">Cloud Messaging</a> plugin:
@@ -666,6 +641,69 @@ startServices();
 
 *Add the following code to the root file of your application, such as `App.js` or `index.js`*
 
+
+📌 **requestLoginPermissions()**
+
+`Note`: Starting from Android 13+, certain foreground services (such as microphone or phone call) require explicit user permission before they can be started.
+This means the user must grant these permissions before initiating a call or any service that relies on them.
+
+```TypeScript
+import { 
+  PERMISSIONS, 
+  request, 
+  check, 
+  RESULTS, 
+  requestMultiple 
+} from 'react-native-permissions';
+import { Platform } from 'react-native';
+
+export async function requestLoginPermissions(): Promise<boolean> {
+  if (Platform.OS !== 'android') return true;
+
+  const permissions: string[] = [];
+
+  // Android 13+ cần POST_NOTIFICATIONS
+  if (Platform.Version >= 33) {
+    permissions.push(PERMISSIONS.ANDROID.POST_NOTIFICATIONS);
+  }
+
+  // Android 14+ và 15+ cần RECORD_AUDIO trước khi start foreground service
+  permissions.push(PERMISSIONS.ANDROID.RECORD_AUDIO);
+
+  const statuses = await requestMultiple(permissions);
+
+  // Check kết quả
+  const allGranted = Object.values(statuses).every(
+    status => status === RESULTS.GRANTED
+  );
+
+  if (!allGranted) {
+    console.warn('❌ Some required permissions were not granted');
+    return false;
+  }
+
+  console.log('✅ All required permissions granted');
+  return true;
+}
+```
+
+Example: use func `requestLoginPermissions()`
+
+```TypeScript
+async function handleLogin() {
+  const ok = await requestLoginPermissions();
+  if (!ok) {
+    // Block login, show alert
+    return;
+  }
+
+  // ✅ Safe để start service login
+  // initCallWithApiKey(); 
+  initCallWithUserPassword()
+}
+```
+
+
 📌 **initCallWithApiKey()**
 
 📝 Notes: The information below is taken from the API, you should connect with our Technical team for support
@@ -745,65 +783,52 @@ const loginInfo = {
 };
 
 // Initialize call functionality using username and password authentication
-const result = await initCallWithUserPassword(loginInfo);
-
+ initCallWithUserPassword(loginInfo)
+      .then(result => {
+        console.log('initCallWithUserPassword success:', result);
 
-/* ❌ ❌ NOTE: Please check the user information again, if the object is not empty then you have successfully logged in. 
+        if (result) {
+        // ✅ Login OMI Success 
+        /* ❌ ❌ NOTE: Please check the user information again, if the object is not empty then you have successfully logged in. 
 Otherwise, if you have not successfully logged in, you should not navigate to the call screen. When startCall with empty information, it may crash your application or not be clear when receiving the startCall error  ❌❌*/
-
-// Example:
-
-if (result){
-  const infoUser = await getCurrentUser()
-  if (infoUser != null && Object.keys(infoUser).length > 0) { 
-    // ✅ Login OMI Success 
-    // Can navigate to call screen or start call 🚀 🚀
-  }
-}
-```
-
-📌 **checkCredentials()** *(OmiSDK 2.3.67+)*
-
-✅ Description: Check credentials without maintaining connection. Useful for validating login information before actual registration.
-
-```javascript
-import { checkCredentials } from 'omikit-plugin';
-
-const loginInfo = {
-  userName: "your_username",
-  password: "your_password", 
-  realm: "your_realm",
-  fcmToken: "your_fcm_token",
-  projectId: "your_project_id"
-};
-
-const result = await checkCredentials(loginInfo);
-console.log(result); 
-// Output: { success: true/false, statusCode: number, message: string }
-```
-
-📌 **registerWithOptions()** *(OmiSDK 2.3.67+)*
-
-✅ Description: Register with full control over notification and auto-unregister behavior.
-
-```javascript
-import { registerWithOptions } from 'omikit-plugin';
-
-const loginInfo = {
-  userName: "your_username",
-  password: "your_password",
-  realm: "your_realm", 
-  isVideo: true,
-  fcmToken: "your_fcm_token",
-  projectId: "your_project_id",
-  showNotification: false,      // Control notification display
-  enableAutoUnregister: false   // Control auto-unregister behavior
-};
-
-const result = await registerWithOptions(loginInfo);
-console.log(result);
-// Output: { success: true/false, statusCode: number, message: string }
-```
+          const infoUser = await getCurrentUser()
+          if (infoUser != null && Object.keys(infoUser).length > 0) { 
+            // ✅ Login OMI Success 
+            // Can navigate to call screen or start call 🚀 🚀
+          }
+        }
+      })
+      .catch(error => {
+        // You can log error and check cause error
+        console.error('initCallWithUserPassword error:', error?.code, error?.message);
+        if (error?.code === 'ERROR_MISSING_RECORD_AUDIO') { // Please request permission audio
+          requestPermission(); 
+        }
+      })
+      .finally(() => {
+        // Doing something 
+        // setLoading(false);
+      });
+```
+📝 **Detailed Description of Possible Errors(error?.code)**
+
+| **Message**                        | **Description**                                                                 | **Next Action**                                                                 |
+|------------------------------------|---------------------------------------------------------------------------------|----------------------------                                        
+| `ERROR_MISSING_PARAMETERS`         | Missing required parameters. Please check your configuration.                   | Verify all required fields are provided                                         |
+| `ERROR_INVALID_CREDENTIALS`        | Invalid credentials. Please check username/password.                            | Double-check login info                                                         |
+| `ERROR_FORBIDDEN`                  | Access denied. Check realm/domain permissions.                                  | Confirm account permissions with provider                                       |
+| `ERROR_REALM_NOT_FOUND`            | Realm not found. Check configuration.                                           | Ensure realm/domain is correct                                                  |
+| `ERROR_TIMEOUT`                    | Connection timeout                                                              | Retry with stable network                                                       |
+| `ERROR_MISSING_RECORD_AUDIO`       | RECORD_AUDIO permission required for Android 14+                                | Ask user to grant microphone permission                                         |
+| `ERROR_MISSING_FOREGROUND_SERVICE` | FOREGROUND_SERVICE permission required                                          | Request foreground service permission before starting service                   |
+| `ERROR_MISSING_POST_NOTIFICATIONS` | POST_NOTIFICATIONS permission required for Android 13+                          | Request notification permission before registering                              |
+| `ERROR_SERVICE_START_FAILED`       | Failed to start SIP service                                                     | Check logs and required permissions                                             |
+| `ERROR_SERVICE_NOT_AVAILABLE`      | SIP service not available                                                       | Ensure service is running                                                       |
+| `ERROR_SERVICE_DEGRADED`           | Service degraded - may miss calls when app killed                               | Keep app in foreground or request proper permissions                            |
+| `ERROR_SERVICE_UNAVAILABLE`        | Service temporarily unavailable                                                 | Try again later                                                                 |
+| `ERROR_NETWORK_UNAVAILABLE`        | Network unavailable                                                             | Check network connection                                                        |
+| `ERROR_CONNECTION_TIMEOUT`         | Connection timeout                                                              | Verify network and server availability                                          |
+| `ERROR_UNKNOWN`                    | Unknown error occurred                                                          | Check logs and report issue                                                     |
 
 📌 **configPushNotification()**
 
@@ -825,8 +850,8 @@ configPushNotification({
   missedCallTitle: "Cuộc gọi nhỡ", // Title for missed call notifications
   userNameKey: "uuid", // User identification key: options are "uuid", "full_name", or "extension"
   channelId: "com.channel.sample", // Custom notification channel ID for Android
-  audioNotificationDescription: "", // Description for audio call notifications
-  videoNotificationDescription: "", // Description for video call notifications
+  audioNotificationDescription: "Cuộc gọi audio", // Description for audio call notifications
+  videoNotificationDescription: "Cuộc gọi video", // Description for video call notifications
   representName: "", // Representative name to display for all incoming calls (e.g., business name)
   isUserBusy: true // By default, it is set to true. The Omicall system will continue ringing the next user if isUserBusy is true. If it is false, the call will be immediately terminated, assuming the call scenario is based on a criteria-based routing.
 });
@@ -1111,39 +1136,6 @@ const result = await startCallWithUuid({
     logout();
 ```
 
-📌 **hideSystemNotificationSafely()** *(OmiSDK 2.3.67+)*
-
-✅ Description: Safely hide system notification and unregister after a delay.
-
-```javascript
-import { hideSystemNotificationSafely } from 'omikit-plugin';
-
-const success = await hideSystemNotificationSafely();
-// Hides notification and unregisters after 2 seconds
-```
-
-📌 **hideSystemNotificationOnly()** *(OmiSDK 2.3.67+)*
-
-✅ Description: Hide system notification only, without unregistering.
-
-```javascript
-import { hideSystemNotificationOnly } from 'omikit-plugin';
-
-const success = await hideSystemNotificationOnly();
-// Keeps registration active but hides notification
-```
-
-📌 **hideSystemNotificationAndUnregister()** *(OmiSDK 2.3.67+)*
-
-✅ Description: Hide notification and unregister with custom reason.
-
-```javascript
-import { hideSystemNotificationAndUnregister } from 'omikit-plugin';
-
-const success = await hideSystemNotificationAndUnregister("User logout");
-// Hides notification and unregisters immediately with reason
-```
-
 📌 **systemAlertWindow()**
 
 ✅ Description: Check system alert window permission (only Android).
@@ -1428,34 +1420,6 @@ const onSwitchboardAnswer = (data: any) => {
 | `864`           | Temporary block on Mobifone direction, please try again |
 | `865`           | he advertising number is currently outside the permitted calling hours, please try again later |
 
-# 🔥 Android 15+ Compatibility Features
-
-## ✨ New in Version 3.3.5+
-
-### **Enhanced Permission Management**
-- **Full Android 15 (SDK 35+) Support**: Automatic handling of new foreground service permissions
-- **Smart Permission Requests**: Built-in functions to request specific permissions by error codes
-- **Comprehensive Status Checking**: Real-time permission status monitoring
-- **Version-Aware Logic**: Automatically handles Android version differences
-
-### **Advanced Registration Options** *(OmiSDK 2.3.67+)*
-- **Silent Registration**: Register without notifications or auto-unregister
-- **Credential Validation**: Check login credentials without connecting
-- **Custom Registration**: Full control over notification and unregister behavior
-- **Notification Management**: Fine-grained control over system notifications
-
-### **Error Code Mapping**
-Complete mapping of OmiSDK status codes to user-friendly error messages:
-- **450**: RECORD_AUDIO permission required for Android 14+
-- **451**: FOREGROUND_SERVICE permission required
-- **452**: POST_NOTIFICATIONS permission required for Android 13+
-- **500-600**: Service and network error handling
-- **Detailed Messages**: Customer-friendly error descriptions for easier integration
-
-### **Development Workflow**
-- **copy_dev.sh**: Efficient development workflow for testing native code changes
-- **Automatic Build Fixes**: Handles gradle namespace issues automatically
-- **Hot Reload**: Quick testing without npm publishing
 
 ### **Breaking Changes**
 - **Android 15+ Support**: Requires additional permissions in AndroidManifest.xml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omikit-plugin",
-  "version": "3.3.7",
+  "version": "3.3.8",
   "description": "Omikit Plugin by ViHAT",
   "main": "lib/commonjs/index",
   "module": "lib/module/index",