Constructor Detail

Method Detail

• getVersion

   final String getVersion()

  Returns the SDK version.

  The version is injected at build time via BuildConfig.VERSION_NAME, sourced from UNIVERSAL_NEXCONN_VERSION in gradle.properties.

  Returns:

  SDK version string

• getCurrentUserId

   final String getCurrentUserId()

  Returns the currently connected user ID.

  Returns null when disconnected.

  val userId = NCEngine.getCurrentUserId()
  if (userId != null) {
      println("Current user: $userId")
  }

  Returns:

  Current user ID, or null if not connected

• addUserHandler

   final Unit addUserHandler(String identifier, UserHandler handler)

  Adds a user event handler.

  Notifies via UserHandler when subscribed user statuses change or friend relationships are modified.

  NCEngine.addUserHandler("USER_HANDLER_ID", object : UserHandler {
      override fun onEventChanged(event: SubscribeEventChangedEvent) {
          event.events.forEach { info ->
              println("User ${info.userId} status changed")
          }
      }
  
      override fun onFriendAdd(event: FriendAddEvent) {
          println("Friend added: ${event.userId}")
      }
  
      override fun onFriendDelete(event: FriendDeleteEvent) {
          println("Friends deleted: ${event.userIds}")
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - User event handler

• removeUserHandler

   final Unit removeUserHandler(String identifier)

  Removes a user event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• initialize

   final Unit initialize(InitParams params)

  Initializes the SDK.

  Must be called before using any other SDK features. It is recommended to call this in Application.onCreate().

  Required parameters: context, appKey (passed via InitParams constructor)

  Optional parameters: (set via InitParams properties)

  • InitParams.logLevel - Log level (default: WARN)

  • InitParams.naviServer - Custom navigation server URL (for private cloud)

  • InitParams.fileServer - Custom file server URL (for private cloud)

  • InitParams.statisticServer - Custom statistics server URL (for private cloud)

  • InitParams.logServer - Custom log server URL (for private cloud)

  • InitParams.areaCode - Area code (default: SG, for overseas deployment)

  • InitParams.enablePush - Whether to enable push notifications (default: true)

  • InitParams.enableSyncEmptyTopConversation - Whether to sync empty pinned channels (default: false)

  • InitParams.compressOptions - Media compression options for images and short videos (default: null, uses SDK defaults)

  Parameters:

  params - Initialization parameters

• connect

   final Unit connect(ConnectParams params, ConnectHandler handler)

  Connects to the server.

  Uses ConnectParams to connect to the Nexconn server. After a successful connection, operations such as sending and receiving messages become available.

  Required parameters: token (passed via ConnectParams constructor)

  Optional parameters: (set via ConnectParams properties)

  • ConnectParams.timeout - Connection timeout in seconds (default: -1, no limit)

  • ConnectParams.reconnectKickEnable - Whether to kick out the reconnecting device (default: false)

  // Basic usage
  NCEngine.connect(ConnectParams("user-token")) { userId, error ->
      if (error == null) {
          // Connected successfully
      }
  }
  
  // With timeout and reconnect kick
  NCEngine.connect(ConnectParams("user-token").apply {
      timeout = 10
      reconnectKickEnable = true
  }) { userId, error ->
      // ...
  }

  Parameters:

  params - Connection parameters

  handler - Connection result callback; returns userId on success, error on failure

• disconnect

   final Unit disconnect(Boolean disablePush)

  Disconnects from the server.

  Parameters:

  disablePush - Whether to stop receiving push notifications after disconnecting.

• getConnectionStatus

   final ConnectionStatus getConnectionStatus()

  Gets the current connection status.

  Returns:

  Current connection status ConnectionStatus

• registerCustomMessages

   final Unit registerCustomMessages(List<Class<out MessageContent>> messageClasses)

  Registers custom message types.

  Define custom messages by extending CustomMessageContent or CustomMediaMessageContent, then call this method after initialize and before connect to register them.

  The SDK will automatically:

  • Read metadata such as message type identifier and storage policy

  • Register the message class type internally

  • Handle encoding and decoding during send/receive

  // 1. Define a custom message (extends CustomMessageContent)
  class CardMessage : CustomMessageContent() {
      var title: String = ""
      var imageUrl: String = ""
      var linkUrl: String = ""
  
      override fun messageType(): String = "app:card"
      override fun persistentFlag(): Int = MessagePersistent.COUNT
  
      override fun encodeFields(): Map<String, Any?> = mapOf(
          "title" to title,
          "imageUrl" to imageUrl,
          "linkUrl" to linkUrl
      )
  
      override fun decodeFields(fields: Map<String, Any?>) {
          title = fields["title"] as? String ?: ""
          imageUrl = fields["imageUrl"] as? String ?: ""
          linkUrl = fields["linkUrl"] as? String ?: ""
      }
  }
  
  // 2. Register the custom message
  NCEngine.registerCustomMessages(listOf(CardMessage::class.java))

  Parameters:

  messageClasses - List of custom message classes extending CustomMessageContent or CustomMediaMessageContent

• getAppSettings

   final AppSettings getAppSettings()

  Gets application-level configuration settings.

  Must be called after a successful connection. Returns feature switches and configuration values managed on the server side.

  val settings = NCEngine.getAppSettings()
  if (settings.isSpeechToTextEnabled) {
      // Speech-to-text is available
  }

  Returns:

  Application settings

• addConnectionStatusHandler

   final Unit addConnectionStatusHandler(String identifier, ConnectionStatusHandler handler)

  Adds a connection status handler.

  Notifies via ConnectionStatusHandler.onConnectionStatusChanged when the connection status changes.

  NCEngine.addConnectionStatusHandler("CONNECTION_HANDLER_ID") { event ->
      when (event.status) {
          ConnectionStatus.CONNECTED -> println("Connected")
          ConnectionStatus.SUSPENDED -> println("Connection suspended")
          else -> println("Status: ${event.status}")
      }
  }

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Connection status handler

• removeConnectionStatusHandler

   final Unit removeConnectionStatusHandler(String identifier)

  Removes a connection status handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addDatabaseStatusHandler

   final Unit addDatabaseStatusHandler(String identifier, DatabaseStatusHandler handler)

  Adds a database upgrade status handler.

  Notifies via DatabaseStatusHandler about the database upgrade progress and result when the SDK's internal database undergoes an upgrade.

  NCEngine.addDatabaseStatusHandler("DB_HANDLER_ID", object : DatabaseStatusHandler {
      override fun onUpgradeWillStart(event: DatabaseUpgradeWillStartEvent) {
          println("Database upgrade starting")
      }
      override fun onUpgrading(event: DatabaseUpgradingEvent) {
          println("Upgrade progress: ${event.progress}%")
      }
      override fun onUpgradeCompleted(event: DatabaseUpgradeCompletedEvent) {
          if (event.error == null) {
              println("Upgrade completed successfully")
          }
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Database status handler

• removeDatabaseStatusHandler

   final Unit removeDatabaseStatusHandler(String identifier)

  Removes a database upgrade status handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addMessageHandler

   final Unit addMessageHandler(String identifier, MessageHandler handler)

  Adds a message event handler.

  Listens for message-related event notifications including message reception, read receipts, message recall, speech-to-text, message modification, and message interception.

  NCEngine.addMessageHandler("MSG_HANDLER_ID", object : MessageHandler {
      override fun onMessageReceived(event: MessageReceivedEvent) {
          println("Received: ${event.message.messageId}")
      }
      override fun onMessageReceiptResponse(event: MessageReceiptResponseEvent) {
          event.responses.forEach { response ->
              println("Message ${response.messageId} read count: ${response.readCount}")
          }
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Message event handler

• removeMessageHandler

   final Unit removeMessageHandler(String identifier)

  Removes a message event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addChannelHandler

   final Unit addChannelHandler(String identifier, ChannelHandler handler)

  Adds a channel status handler.

  Listens for channel status sync events (pinned, do-not-disturb, etc.) and channel translation strategy changes across multiple devices.

  NCEngine.addChannelHandler("CHANNEL_HANDLER_ID", object : ChannelHandler {
      override fun onChannelPinnedSync(event: ChannelPinnedSyncEvent) {
          println("Channel ${event.channelIdentifier.channelId} pinned: ${event.isPinned}")
      }
      override fun onChannelNoDisturbLevelSync(event: ChannelNoDisturbLevelSyncEvent) {
          println("Channel ${event.channelIdentifier.channelId} DND level: ${event.level}")
      }
      override fun onChannelStatusSyncCompleted(event: ChannelStatusSyncCompletedEvent) {
          if (event.error == null) {
              println("Channel status sync completed")
          }
      }
      override fun onChannelTranslateStrategySync(event: ChannelTranslateStrategySyncEvent) {
          println("Channel ${event.channelIdentifier.channelId} translate strategy: ${event.strategy}")
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Channel status handler

• removeChannelHandler

   final Unit removeChannelHandler(String identifier)

  Removes a channel status handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addTranslateHandler

   final Unit addTranslateHandler(String identifier, TranslateHandler handler)

  Adds a translation event handler.

  Listens for translation-related event notifications including translation completion, translation language changes, and user-level auto-translation status changes.

  NCEngine.addTranslateHandler("TRANSLATE_HANDLER_ID", object : TranslateHandler {
      override fun onTranslationCompleted(event: TranslationCompletedEvent) {
          event.results.forEach { result ->
              println("Translation completed: ${result.identifier}")
          }
      }
      override fun onTranslationLanguageChanged(event: TranslationLanguageChangedEvent) {
          println("Translation language changed to: ${event.language}")
      }
      override fun onAutoTranslateStateChanged(event: AutoTranslateStateChangedEvent) {
          println("Auto-translation enabled: ${event.isEnabled}")
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Translation event handler

• removeTranslateHandler

   final Unit removeTranslateHandler(String identifier)

  Removes a translation event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addTagHandler

   final Unit addTagHandler(String identifier, TagHandler handler)

  Adds a tag event handler.

  Listens for tag-related multi-device sync events, including tag changes and tag-channel association changes.

  NCEngine.addTagHandler("TAG_HANDLER_ID", object : TagHandler {
      override fun onTagChanged(event: TagChangedEvent) {
          // Tag changed, refresh tag list
          Tag.getTags { tags, error -> ... }
      }
      override fun onChannelTagChanged(event: ChannelTagChangedEvent) {
          // Tag-channel association changed
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Tag event handler

• removeTagHandler

   final Unit removeTagHandler(String identifier)

  Removes a tag event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addUserSettingsHandler

   final Unit addUserSettingsHandler(String identifier, UserSettingsHandler handler)

  Adds a user settings event handler.

  After connection, the SDK syncs all user-level settings. This handler is notified when the sync completes.

  NCEngine.addUserSettingsHandler("USER_SETTINGS_ID", object : UserSettingsHandler {
      override fun onUserSettingsSyncCompleted(event: UserSettingsSyncCompletedEvent) {
          if (event.error == null) {
              // User settings synced successfully
          }
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - User settings event handler

• removeUserSettingsHandler

   final Unit removeUserSettingsHandler(String identifier)

  Removes a user settings event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addGroupChannelHandler

   final Unit addGroupChannelHandler(String identifier, GroupChannelHandler handler)

  Adds a group channel event handler.

  Listens for group-related events including group operations (create, join, kick, dismiss, etc.), group info changes, member info changes, application events, and favorites (special-follow) sync events.

  NCEngine.addGroupChannelHandler("GROUP_HANDLER_ID", object : GroupChannelHandler {
      override fun onGroupOperation(event: GroupOperationEvent) {
          println("Group ${event.groupId} operation: ${event.operation}")
      }
  
      override fun onGroupInfoChanged(event: GroupInfoChangedEvent) {
          println("Group info changed, properties: ${event.changedProperties}")
      }
  
      override fun onGroupApplicationEvent(event: GroupApplicationEvent) {
          println("Group application: ${event.info.groupId}, type: ${event.info.type}")
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Group channel event handler

• removeGroupChannelHandler

   final Unit removeGroupChannelHandler(String identifier)

  Removes a group channel event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• addOpenChannelHandler

   final Unit addOpenChannelHandler(String identifier, OpenChannelHandler handler)

  Adds an open channel event handler.

  Listens for all open channel events in a unified manner, including:

  • Operation events: join, leave, destroy, reset, error

  • Notification events: multi-device sync, member ban, member mute

  • Metadata events: KV sync, change (update/delete)

  • Member changes: member join and leave

  All callback methods have default empty implementations; callers only need to override the callbacks they are interested in.

  NCEngine.addOpenChannelHandler("OPEN_CHANNEL_ID", object : OpenChannelHandler {
      override fun onEntered(event: OpenChannelEnteredEvent) {
          println("Joined channel: ${event.channelId}")
      }
      override fun onMemberChanged(event: OpenChannelMemberChangedEvent) {
          println("Channel: ${event.channelId}, total members: ${event.totalCount}")
      }
      override fun onMetadataChanged(event: OpenChannelMetadataChangedEvent) {
          event.changes.forEach { println("KV ${it.key} = ${it.value}, deleted: ${it.isDelete}") }
      }
  })

  Parameters:

  identifier - Unique identifier for the handler, used for subsequent removal

  handler - Open channel event handler

• removeOpenChannelHandler

   final Unit removeOpenChannelHandler(String identifier)

  Removes an open channel event handler.

  Parameters:

  identifier - The identifier used when adding the handler

• setNoDisturbTime

   final Unit setNoDisturbTime(NoDisturbTimeParams params, ErrorHandler handler)

  Sets the do-not-disturb time for message notifications.

  Configures the notification quiet hours level for a specified time period.

  val params = NoDisturbTimeParams(
      startTime = "22:00:00",
      spanMinutes = 480,
      level = NoDisturbTimeLevel.MUTED,
      timezone = "Asia/Shanghai"
  )
  NCEngine.setNoDisturbTime(params) { error ->
      if (error == null) {
          // Successfully set
      }
  }

  Parameters:

  params - Do-not-disturb parameters including start time, duration, level, and time zone

  handler - Operation result callback; error is null on success

• getNoDisturbTime

   final Unit getNoDisturbTime(OperationHandler<NoDisturbTimeInfo> handler)

  Gets the current do-not-disturb time settings.

  Returns the currently configured notification quiet hours, including start time, duration, level, and time zone.

  NCEngine.getNoDisturbTime { info, error ->
      if (error == null && info != null) {
          println("Quiet hours start at: ${info.startTime}, duration: ${info.spanMinutes} min")
      }
  }

  Parameters:

  handler - Callback returning the do-not-disturb time info on success

• removeNoDisturbTime

   final Unit removeNoDisturbTime(ErrorHandler handler)

  Removes the do-not-disturb time settings.

  Clears the currently configured notification quiet hours, restoring default notification behavior.

  NCEngine.removeNoDisturbTime { error ->
      if (error == null) {
          // Successfully removed
      }
  }

  Parameters:

  handler - Operation result callback; error is null on success

• getUserModule

   final UserModule getUserModule()

  User module (singleton).

  Provides user-related features including subscription event management, online status queries, user profile management, and friend management.

  NCEngine.userModule.subscribeEvent(params) { failedUserIds, error ->
      // ...
  }

• getTranslateModule

   final TranslateModule getTranslateModule()

  Translation module (singleton).

  Provides translation-related features including message translation, text translation, translation language management, auto-translation toggle, and channel translation strategy configuration.

  NCEngine.translateModule.translateMessages(params) { error ->
      // ...
  }