SDKsuni-app / uni-app xIncludes Enterprise features

Events overview

The UniApp SDK provides dedicated listener registration functions for connection lifecycles, background data synchronization, user profiles, relationships, conversations, groups, messages, file uploads, and audio/video calling. Each registration call returns an OpenIMSDKEventSubscription reference, which you pass to off() to unregister that specific listener.

Always register stable function references rather than inline closures within re-rendering components to prevent memory leaks and duplicate handler execution. Global connection, messaging, and call listeners should reside in application- or session-level stores, while listeners scoped to a specific view should be unsubscribed when that page unmounts.

Recommended registration lifecycles

Event domain	Recommended lifecycle	Detailed documentation
Connection, token, and kick-out	Register before login; clean up when switching accounts	Authenticate and manage a session
User profile, friends, and blacklist	Register when initializing the contact state layer	User overview
Conversation list and unread counts	Register when initializing the conversation state layer	Get the conversation list, Get total unread count
Groups and group members	Register when initializing the group state layer	Group overview
Group join applications	Register when initializing group application management	Get received group applications
Messages and receipts	Register when initializing the message store	Receive messages
File uploads	Register before initiating upload tasks	Upload a file
Audio/video calls	Register when initializing calling services	Handle call events

Monitor server data synchronization

After successful login, the SDK synchronizes historical records and offline changes from OpenIMServer. Use these four events to track synchronization progress:

Event	Callback parameter	Description
`onSyncServerStart`	`boolean`	Emitted when a synchronization cycle begins.
`onSyncServerProgress`	`number`	The current synchronization percentage (`0` to `100`).
`onSyncServerFinish`	`boolean`	Emitted when synchronization completes successfully.
`onSyncServerFailed`	`boolean`	Emitted when synchronization fails.

The callback parameters for onSyncServerStart, onSyncServerFinish, and onSyncServerFailed are booleans without specific payload properties. Determine the sync phase by the event name itself rather than attempting to interpret the boolean payload.

Code example

import {
  off,
  onSyncServerFailed,
  onSyncServerFinish,
  onSyncServerProgress,
  onSyncServerStart,
} from '@/uni_modules/unix-openim-sdk'

const handleSyncStart = (_value: boolean) => {
  setSyncState('syncing', 0)
}

const handleSyncProgress = (progress: number) => {
  setSyncState('syncing', progress)
}

const handleSyncFinish = (_value: boolean) => {
  setSyncState('ready', 100)
  void reloadVisibleData()
}

const handleSyncFailed = (_value: boolean) => {
  setSyncState('failed', 0)
}

const syncStartSubscription = onSyncServerStart(handleSyncStart)
const syncProgressSubscription = onSyncServerProgress(handleSyncProgress)
const syncFinishSubscription = onSyncServerFinish(handleSyncFinish)
const syncFailedSubscription = onSyncServerFailed(handleSyncFailed)

function removeSyncListeners() {
  off(syncStartSubscription)
  off(syncProgressSubscription)
  off(syncFinishSubscription)
  off(syncFailedSubscription)
}

Synchronization events describe the SDK's background sync lifecycle rather than a specific query API. Once synchronization completes, refresh view models for active screens, and rely on domain-specific events for subsequent real-time updates. Because events can arrive out of order during network transitions, merge items into your state using stable keys: userID, conversationID, groupID, groupID:userID, or clientMsgID.

Was this page helpful?