Connect

The app client must connect to the Nexconn server before sending or receiving messages.

When the server receives a connection request, it validates the user's access token (the token parameter) to determine whether to allow the connection.

Prerequisites

• Obtain an access token by calling the Register User (Get Token) Server API. The client SDK does not provide a method to get a token — your app server must request it from the Nexconn server.
  • After obtaining the token, save it on the client for subsequent connections. The storage location depends on your app design. If the token has not expired, there is no need to request a new one.
  • Token expiration is configurable in the console. By default, tokens never expire. Even after generating a new token, unexpired old tokens remain valid. If a token expires, request a new one. To manually invalidate a token, call the Expire Token Server API.
• Set a connection status handler before connecting.
• Complete SDK initialization.

warning

Never call the Server API directly from the client to obtain a token. Getting a token requires the App Key and App Secret. If these credentials are stored on the client, they may be exposed through decompilation. Always obtain tokens from your app server.

Connect to the server

Choose the appropriate time to connect based on your app's requirements — for example, at login, registration, or another point that ensures the user can reach the main screen.

Method

Dart

static Future<int> connect(ConnectParams params, OprationHandler<String> handler)

Parameters

Parameter	Type	Description
params	ConnectParams	Connection parameters.
handler	OprationHandler<String>	Callback receiving (userId, error). userId is set on success; error is set on failure.

ConnectParams

Property	Type	Description
token	String	Required. The access token for authenticating the user session.
timeout	int	Connection timeout in seconds. Default: 30.

Return value

Return value	Description
Future<int>	Immediate status code for the API call. 0 means the connect request was dispatched successfully; check handler for the final result. Non-zero means the call failed immediately, and handler also receives the corresponding NCError. If NCEngine.initialize() has not been called, the method returns -1 and handler receives an initialization error.

Code example

Dart

await NCEngine.connect(
  ConnectParams(token: '<your-token>'),
  (userId, error) {
    if (error == null) {
      print('Connected as: $userId');
    } else {
      print('Connection failed: $error');
    }
  },
);

tip

1. The SDK has a built-in reconnection mechanism. Call connect() only once per app lifecycle. Calling it multiple times may trigger multiple callbacks and cause callbacks to be cleared.
2. When the error code is 31004, request a new token from your server and reconnect. Avoid infinite loops to prevent degrading the user experience.

Troubleshooting invalid token (31004)

Cause	Solution
Incorrect token	Verify that the App Key used for client initialization matches the App Key used by your server to obtain the token.
Expired token	Check whether you configured a token expiration time on the console's Key Management page. After expiration, request a new token from your server and reconnect.

Error codes

See the native platform error code definitions: Android error codes and iOS error codes.