Login

Feature Introduction

Description

User login requires waiting for a successful callback (rather than a successful return) before calling other interfaces. You need to call the login interface in the following scenarios: 1) After the APP starts, and after retrieving a new token from the server. 2) After logging in, the token expires and a new token is retrieved from the server. 3) After being forcibly logged out by the APP administrator and a new token is retrieved from the server. 4) After the user actively logs out and a new token is retrieved from the server.

You don't need to call the login interface in the following scenarios: 1) When the user's internet disconnects and reconnects. 2) When a login process has not yet completed.

Note

1) If a failure callback appears, retrying is pointless. Check the error message, review the parameters, adjust the code, and continue. 2) Within an app, the SDK does not support logging in with multiple accounts simultaneously. You must log out first before logging in with another account. 3) Apart from setting listeners, initializing, and checking login status, all other interfaces must only be called after the SDK login callback is successful.

iOS

Function Prototype

 Future<UserInfo> login({
    required String userID,
    required String token,
    String? operationID,
    Future<UserInfo> Function()? defaultValue,
  })

Input Parameters

Parameter Name	Parameter Type	Mandatory	Description
operationID	String?	No	Operation ID for problem tracking. Keep unique, suggested to use current timestamp combined with a random number.
userID	String	Yes	IM user userID
token	String	Yes	OpenIM user token. After backend verifies user credentials, it's obtained through user_token.

Return Result

Name	Data Type	Description
~	UserInfo	Current logged-in user information

Code Example

   UserInfo userInfo = await OpenIM.iMManager.login(userID: '', token: '');

Android

Function Prototype

- (void)login:(NSString *)userID
        token:(NSString *)token
    onSuccess:(nullable OIMSuccessCallback)onSuccess
    onFailure:(nullable OIMFailureCallback)onFailure;

Input Parameters

Parameter Name	Parameter Type	Mandatory	Description
operationID	NSString	No	Operation ID for problem tracking. Keep unique, suggested to use current timestamp combined with a random number.
userID	NSString	Yes	IM user userID
token	NSString	Yes	OpenIM user token. After backend verifies user credentials, it's obtained through user_token.

Return Result

Parameter Name	Parameter Type	Description
onSuccess	OIMSuccessCallback	Successful return
onFailure	OIMFailureCallback	Failure return

Code Example

[OIMManager.manager login:@"" // userID obtained from your own business server
                    token:@""  // token acquired by business server from OpenIM server
                onSuccess:^(NSString * _Nullable data) {
} onFailure:^(NSInteger code, NSString * _Nullable msg) {
}];

Flutter

Function Prototype

     public void login(@NotNull final OnBase<String> callBack, String uid, String token)

Parameter Details

Parameter Name	Parameter Type	Mandatory	Description
callBack	OnBase	Yes	Callback interface
userID	String	Yes	IM user userID
token	String	Yes	OpenIM user token. After backend verifies user credentials, it's obtained through user_token.

---

Code Example

     OpenIMClient.getInstance().login(new OnBase<String>() {
                        @Override
                        public void onError(int code, String error) {

                        }

                        @Override
                        public void onSuccess(String data) {

                        }
                    }, userID, imToken);

uni-app

Attention

open-im-sdk-wasm is designed for most browser scenarios, while open-im-sdk is specifically for mini-programs. The wsAddr parameter during login differs between the two, so be careful not to mix them up. For open-im-sdk-wasm, the wsAddr is usually ws://your-server-ip:10001, and the default port used is 10001. For open-im-sdk, the wsAddr is usually ws://your-server-ip:10003, and the default port used is 10003.

Function Prototype

IMSDK.login(config: InitAndLoginConfig, operationID?: string): Promise<WsResponse>

Input Parameters

Parameter Name	Parameter Type	Required	Description
config	InitAndLoginConfig	Yes	Initialization, login parameters
operationID	string	No	Operation ID, for problem location, unique, suggested to use current time and random number

Return Results

Parameter Name	Parameter Type	Description
Promise.then()	Promise<WsResponse>	Successful callback
Promise.catch()	Promise<WsResponse>	Failure callback

Code Example

import { getSDK } from 'open-im-sdk-wasm';
const IMSDK = getSDK();

// use in electron with ffi
// import { getWithRenderProcess } from '@openim/electron-client-sdk/lib/render';
// const { instance: IMSDK } = getWithRenderProcess();

// use in mini program
// import { OpenIMSDK } from 'open-im-sdk';
// const IMSDK = new OpenIMSDK();

const config = {
    userID: string;       // IM user userID
    token: string;        // IM user token
    platformID: number;   // Current login platform number
    apiAddr: string;   // IM api address, generally `http://xxx:10002` or `https://xxx/api
    wsAddr: string;    // IM ws address, generally `ws://your-server-ip:10001`(open-im-sdk-wasm) or `ws://your-server-ip:10003`(open-im-sdk)
}
IMSDK.login(config)
  .then(() => {
    // Login successful
  })
  .catch(({ errCode, errMsg }) => {
    // Login failed
  });

Browser/Electron/MiniProgram

Function Prototype

IMSDK.asyncApi('login', operationID: string, {
  userID: string,
  token: string
}): Promise<void>

Input Parameters

Parameter Name	Parameter Type	Required	Description
operationID	string	Yes	Operation ID, for problem location, keep unique, suggested to use current time and random number
userID	string	Yes	IM user userID
token	string	Yes	OpenIM user token. After business backend verifies user credentials, it can be obtained through auth/user_token

Return Results

With the openim-uniapp-polyfill package, the function is made into a Promise. When calling, use then and catch to determine and handle successful and failed callbacks.

Parameter Name	Parameter Type	Description
Promise.then()	Promise<void>	Successful callback
Promise.catch()	Promise<CatchResponse>	Failure callback

Code Example

import IMSDK from 'openim-uniapp-polyfill';

IMSDK.asyncApi('login', IMSDK.uuid(), {
  userID: '',
  token: '',
})
  .then(() => {
    // Login successful
  })
  .catch(({ errCode, errMsg }) => {
    // Login failed
  });

React-Native

### Function Prototype

OpenIMSDKRN.login({
  userID:string, 
  token:string
}, operationID:string): Promise<void>

Input Parameters

Parameter Name	Parameter Type	Mandatory	Description
userID	String	Yes	IM userID
token	String	Yes	OpenIM user token. After business backend verifies user credentials, it can be obtained through auth/user_token
operationID	String	Yes	Operation ID, used for problem location, keep unique, suggest using current time and random number

Return Result

Parameter Name	Parameter Type	Description
Promise.then()	Promise<void>	Callback on successful call
Promise.catch()	Promise<CatchResponse>	Callback on failed call

Code Example

import OpenIMSDKRN from 'open-im-sdk-rn';

OpenIMSDKRN.login({
  userID: 'IM user ID',
  token: 'IM user token',
}, 'operationID')
  .then(() => {
    // Login successful
  })
  .catch(({ errCode, errMsg }) => {
    // Login failed
  });

Unity

Function Prototype

public static void Login(string uid, string token, OnSucOrError cb)

Input Parameter

Parameter Name	Parameter Type	Mandatory	Description
uid	string	Yes	IM userID
token	string	Yes	OpenIM user token. After business backend verifies user credentials, it can be obtained through auth/user_token
cb	OnSucOrError	Yes	Callback

Code Example

IMSDK.Login(userId, token, (suc, errCode, errMsg) =>
{
    if (suc)
    {
        OnLoginSuc(userId, token);
    }
});