@droppii/chat-mobile

Droppii chat mobile

Installation

npm install @droppii/chat-mobile

Usage

Installation dependencies

@droppii/chat-mobile requires the following peer dependencies:

npm install react-native-fs

react-native-fs is used to resolve the local path for dataDir and logFilePath.

initChatSdk(options)

Khởi tạo Chat SDK. Gọi hàm này một lần duy nhất khi ứng dụng khởi động, trước khi render bất kỳ component nào sử dụng tính năng chat.

import { initChatSdk } from '@droppii/chat-mobile';
import RNFS from 'react-native-fs';

initChatSdk({
  apiAddr: 'https://your-api-server.com',   // REST API endpoint
  wsAddr: 'wss://your-ws-server.com',       // WebSocket endpoint
  dataDir: RNFS.DocumentDirectoryPath + '/chat',      // Thư mục lưu trữ dữ liệu SDK
  logFilePath: RNFS.DocumentDirectoryPath + '/chat',  // Thư mục lưu file log
  logLevel: 5,              // LogLevel.Debug (xem bảng bên dưới)
  isLogStandardOutput: true, // In log ra console (nên bật khi develop)
});

Tham số InitOptions

| Tham số | Kiểu | Bắt buộc | Mô tả | | --------------------- | ---------- | :------: | --------------------------------------------------------- | | apiAddr | string | ✅ | URL của REST API server | | wsAddr | string | ✅ | URL của WebSocket server | | dataDir | string | ✅ | Đường dẫn thư mục lưu dữ liệu cục bộ (SQLite, cache...) | | logFilePath | string | ✅ | Đường dẫn thư mục lưu file log | | logLevel | LogLevel | ✅ | Mức độ log (xem bảng LogLevel bên dưới) | | isLogStandardOutput | boolean | ✅ | true để in log ra stdout (hữu ích khi debug) |

LogLevel

| Giá trị | Hằng số | Mô tả | | :-----: | -------------- | ------------------------------ | | 5 | Debug | Tất cả log (verbose) | | 4 | Info | Thông tin chung | | 3 | Warn | Cảnh báo | | 2 | Error | Chỉ lỗi | | 1 | Fatal | Lỗi nghiêm trọng | | 0 | Panic | Lỗi làm crash ứng dụng |

Ví dụ thực tế (trong App.tsx)

import { initChatSdk } from '@droppii/chat-mobile';
import RNFS from 'react-native-fs';

// Gọi ở top-level module, trước khi App render
initChatSdk({
  apiAddr: process.env.CHAT_API_URL!,
  wsAddr: process.env.CHAT_WS_URL!,
  dataDir: RNFS.DocumentDirectoryPath + '/chat',
  logFilePath: RNFS.DocumentDirectoryPath + '/chat',
  logLevel: __DEV__ ? 5 : 2, // Debug khi dev, Error khi production
  isLogStandardOutput: __DEV__,
});

export default function App() {
  // ...
}

registerUIUtils(adapter)

@droppii/chat-mobile không tự import UI framework nào để hiển thị toast/alert/popup — consumer tự cung cấp implementation qua registerUIUtils, dùng đúng design system của app mình. Nếu không gọi, lib fallback về Alert.alert mặc định của React Native.

import { registerUIUtils } from '@droppii/chat-mobile';
import { Toast } from '@droppii/libs';

registerUIUtils({
  toast: {
    open: ({ title, message }) => Toast.show({ title, message }),
  },
  alert: {
    open: ({ title, message }) => Alert.alert(title, message), // hoặc custom alert riêng
  },
  popup: {
    open: ({ title, message }) => MyCustomPopup.show({ title, message }),
  },
});

| Tham số | Kiểu | Bắt buộc | Mô tả | | -------- | -------------------------------- | :------: | ---------------------------------------------------------------------- | | toast | { open: (params) => void } | ❌ | Hiển thị toast. Không cung cấp → fallback Alert.alert | | alert | { open: (params) => void } | ❌ | Hiển thị alert. Không cung cấp → fallback Alert.alert | | popup | { open: (params) => void } | ❌ | Hiển thị popup. Không cung cấp → fallback Alert.alert |

Chỉ cần override những UI element nào bạn muốn custom — các key còn lại tự dùng default. Gọi 1 lần lúc app khởi động, cùng chỗ với initChatSdk.

Push Notification Setup

@droppii/chat-mobile không tự tích hợp bất kỳ push provider nào (Firebase, OneSignal...) — consumer tự chọn stack push riêng, chỉ cần forward token cho lib để đăng ký với OpenIM server.

registerPushToken(fcmToken, expireTime?)

Đăng ký push token với OpenIM server. Gọi sau khi login thành công, và mỗi khi token refresh.

import messaging from '@react-native-firebase/messaging';
import { registerPushToken } from '@droppii/chat-mobile';

const token = await messaging().getToken();
await registerPushToken(token);

messaging().onTokenRefresh((newToken) => {
  registerPushToken(newToken);
});

| Tham số | Kiểu | Bắt buộc | Mô tả | | ------------ | -------- | :------: | ---------------------------------------------------------------------- | | fcmToken | string | ✅ | Token lấy từ push provider (Firebase Messaging, OneSignal...) | | expireTime | number | ❌ | TTL của token, đơn vị giây. Mặc định 7776000 (90 ngày) nếu bỏ qua |

unregisterPushToken()

Gọi khi logout, để tránh thiết bị cũ tiếp tục nhận push của user mới (nếu dùng chung thiết bị).

import { unregisterPushToken } from '@droppii/chat-mobile';

await unregisterPushToken();

⚠️ Convention "clear" token chưa được OpenIM tài liệu hoá chính thức — implementation hiện tại gọi updateFcmToken('', 0) (theo convention phổ biến của Firebase), cần confirm thêm với backend/OpenIM team trước khi rely vào production.

syncAppBackgroundStatus(isBackground) — tự động, thường không cần gọi tay

Lib đã tự động lắng nghe AppState và gọi hàm này bên trong useChatSdk() — quyết định OpenIM server route tin nhắn qua WebSocket (foreground) hay offline push (background). Chỉ cần gọi tay nếu có logic "background" riêng ngoài AppState chuẩn (ví dụ: đang trong màn hình gọi video, có overlay che...).

import { syncAppBackgroundStatus } from '@droppii/chat-mobile';

// Chỉ dùng khi cần override thủ công, ngoài AppState mặc định
await syncAppBackgroundStatus(true);

registerBackgroundStatusResolver(resolver) — override logic tính background

Mặc định lib coi mọi state khác 'active' là background. Nếu app có logic riêng (ví dụ: không tính background khi đang có modal gọi video), override qua hàm này — lib vẫn tự động gọi qua AppState listener nội bộ, chỉ đổi logic tính toán.

import { registerBackgroundStatusResolver } from '@droppii/chat-mobile';

registerBackgroundStatusResolver((state) => state !== 'active' && !isInCallScreen());

Setup Firebase cho project (ví dụ tham khảo)

Xem exampleLegacy/ trong repo này để tham khảo cách tích hợp @react-native-firebase/messaging đầy đủ (Android Gradle, iOS Podfile với modular_headers, permission, entitlements). Lưu ý quan trọng khi dùng RNFirebase với static linking (không use_frameworks! global):

# ios/Podfile
$RNFirebaseAsStaticFramework = true

target 'YourApp' do
  # GoogleUtilities không define Swift module theo mặc định — bắt buộc modular_headers
  # nếu không pod install sẽ fail với lỗi "cannot yet be integrated as static libraries"
  pod 'Firebase', :modular_headers => true
  pod 'FirebaseCore', :modular_headers => true
  pod 'FirebaseCoreExtension', :modular_headers => true
  pod 'FirebaseCoreInternal', :modular_headers => true
  pod 'FirebaseInstallations', :modular_headers => true
  pod 'GoogleDataTransport', :modular_headers => true
  pod 'GoogleUtilities', :modular_headers => true
  # ...
end

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library