Before you start

Before integrating the OpenIM WASM SDK into a browser application, prepare an accessible OpenIMServer deployment, the current user's sign-in details, and the SDK runtime assets. These prerequisites apply to both authenticating and managing a session and sending your first message.

Prepare OpenIMServer

If you do not yet have an OpenIMServer deployment, follow the Docker deployment guide. Then verify that the browser can reach apiAddr and wsAddr, including HTTPS/WSS, reverse proxy, and cross-origin settings.

Browser sign-in requires the following service addresses:

Do not only verify that the services are reachable from an internal network or the server itself. Test from the deployed application as well, and confirm that cross-origin settings, HTTPS certificates, reverse proxy rules, and WebSocket upgrades all work correctly.

Prepare the user and token

userID identifies an OpenIMSDK user, while the token authenticates that user. The application backend creates or binds OpenIMSDK users, issues tokens, and enforces application permissions. The browser uses the user-level sign-in details returned by that backend.

Before integrating your backend with the OpenIMServer REST API, see Prepare to use the Platform API and Issue a session token. If your product already has an account system, maintain a stable mapping between each application account and its OpenIMSDK userID, and make sure the returned token belongs to that userID.

The application backend can expose a session endpoint that returns the information required by the SDK:

type OpenIMSDKSession = {
  userID: string;
  token: string;
  apiAddr: string;
  wsAddr: string;
};

async function loadOpenIMSDKSession(): Promise<OpenIMSDKSession> {
  const response = await fetch('/api/openim/session');
  if (!response.ok) throw new Error('Failed to load OpenIMSDK session.');
  return response.json();
}

The application session endpoint returns the OpenIMSDK sign-in details for the current application account. The userID and token must belong to the same user.

Prepare the browser runtime

The OpenIM WASM SDK depends on WebAssembly, WebSocket, and IndexedDB in the browser. Your project must also publish openIM.wasm, sql-wasm.wasm, and wasm_exec.js, and the page must be able to load them from the configured static asset paths.

If your application uses a server-rendering framework such as Next.js, Nuxt, or Remix, initialize the SDK, access the local database, and establish connections only in the browser. See Integrate by runtime for initialization locations and lifecycle handling in different environments.

Before a production release, test the environments and networks your product actually supports:

• All three SDK assets load successfully, and their responses have not been replaced by a sign-in page or error page.
• apiAddr accepts HTTP requests and wsAddr completes a WebSocket connection.
• IndexedDB can create and write to the local database.
• Private browsing, low-storage conditions, and restoring the page after it enters the background behave as your product expects.

Continue the integration

After preparing these shared prerequisites, authenticate and manage the session. Once the connection succeeds, send your first message to a prepared user or group and verify the messaging flow.