SDK · React Native

@imcore/sdk/react-native adds persistent storage, mobile lifecycle handling, network-aware reconnects, and React Native file uploads to the typed imcore SDK. It works with Expo and bare React Native and has no native module of its own.

Install

npm install @imcore/sdk @react-native-async-storage/async-storage \
  @react-native-community/netinfo

Create a client

import { AppState } from 'react-native';
import AsyncStorage from '@react-native-async-storage/async-storage';
import NetInfo from '@react-native-community/netinfo';
import { createReactNativeClient } from '@imcore/sdk/react-native';

const im = createReactNativeClient({
  url: 'wss://im.example.com/acc',
  auth: {
    getToken: () => authStore.accessToken,
    getLogin: () => ({ userID: authStore.userID, userName: authStore.userName }),
  },
  storage: AsyncStorage,
  storageNamespace: `@my-app/imcore/${authStore.userID}/`,
  appState: AppState,
  netInfo: NetInfo,
});

await im.start();
await im.dm.send({ targetUserID: '1002', text: 'hello from mobile' });

// On logout: removes AppState/NetInfo listeners and closes the socket.
im.stop();

React Native’s WebSocket does not expose a portable way to set an Origin header. Deployments that reject an empty origin must set auth.allow_empty_origin: true for native mobile clients (or enforce the equivalent policy at a trusted gateway). JWT authentication remains required.

React Native’s global WebSocket, fetch, and FormData are used directly. start() connects only while the app is reachable and not in the background. By default the socket is released on background and restored on active; set disconnectOnBackground: false when the host app owns that policy.

Use a per-account storageNamespace if the app can switch users. The SDK uses the supplied AsyncStorage for the message cache, offline queue, drafts, and remembered push registration.

Offline send and reconnect catch-up

const result = await im.dm.sendQueued({
  targetUserID: '1002',
  text: 'send when the network returns',
});

im.on('reconnected', async () => {
  await im.dm.historyPage({ targetUserID: '1002', afterID: lastMessageID });
  await im.operations.deviceSyncState();
});

The persistent queue auto-flushes after authentication. reconnected still requires the app to pull any state missed while suspended.

File upload

Pass the file descriptor returned by an image/document picker directly:

const uploaded = await im.media.upload({
  file: {
    uri: picked.assets[0].uri,
    name: picked.assets[0].fileName ?? 'photo.jpg',
    type: picked.assets[0].mimeType ?? 'image/jpeg',
  },
  type: 'image',
  scene: 'dm',
  targetUserID: '1002',
});

await im.dm.send({ targetUserID: '1002', segments: [uploaded.segment] });

The SDK does not request photo, camera, notification, or network permissions; the host app remains responsible for those platform capabilities.

中文说明

React Native 入口复用完整 TypeScript 协议能力，并额外处理 AsyncStorage 持久化、AppState 前后台断连/恢复、NetInfo 网络恢复重连，以及文件选择器 返回的 { uri, name, type } 上传格式。登录后调用一次 start()，退出登录时 调用 stop()；多账号应用务必为每个账号配置不同的 storageNamespace。原生 WebSocket 无法可靠自定义 Origin，服务端需配置 auth.allow_empty_origin: true （或由可信网关实施等价策略），JWT 鉴权仍然必须开启。