Manual Login

Generally, when you log in to the APP for the first time, switch another account to log in APP, or log out App and log in again, manual login is required and the function public static void Login(string appKey, string account, string token, LoginResultDelegate handler = null)shall be invoked to execute login. The delegation LoginResultDelegate shall be configured to get different status of login process. For normal login, the callback will be returned for three times to indicate different processes of login respectively. For different steps in login process and returned error codes, refer to enumeration NIMLoginStep and ResponseCode description. When the login step is NIMLoginStep.kNIMLoginStepLogin and error code is ResponseCode.kNIMResSuccess, it means that login is successful.

• API prototype

csharp/// <summary>
/// Log in NIM client
/// </summary>
/// <param name="appKey">The app key.</param>
/// <param name="account">The account.</param>
/// <param name="token">Token (login token bound at background) </param>
/// <param name="handler">Callback function for login process</param>
public static void Login(string appKey, string account, string token, LoginResultDelegate handler = null)

• Example

csharpprivate void DoLogin()
{
    NIM.ClientAPI.Login("YOUR APPKEY", "ACCOUNT", "PASSWORD", HandleLoginResult);

}

private void HandleLoginResult(NIM.NIMLoginResult result)
{
    //Process login result
    switch(result.LoginStep)
    {
        case NIMLoginStep.kNIMLoginStepLinking:
        //Create connection
        break;
        case NIMLoginStep.kNIMLoginStepLink:
        //Connect to server
        break;
        case NIMLoginStep.kNIMLoginStepLogin:
        //Verify login
            if (result.Code == NIM.ResponseCode.kNIMResSuccess)
            {
                //login successful
            }
            else
            {
                //Login failed. The reason for failed login is checked by result.Code.
            }
        break;
    }
}

• Registration of SDK callback

  After login, SDK will synchronize team information, offline message, roaming message and system notification, so that some global callbacks shall be registered in advance before first login ( For detailed description, refer to API document).

Auto Login

After network disconnection, SDK will monitor network status and automatically execute login when the network is available. SDK provides callback for network disconnection and automatic login result. Developers can register these callback functions to get the results, and notify the users or make other processing as required in callback functions.

• API prototype

csharp/// <summary>
/// Register the callback for automatic re-connection at NIM client If the reconnection fails because server returns an error code different from kNIMResSuccess, instead of resulting from network error (related error code kNIMResTimeoutError and kNIMResConnectionError), it means that the mechanism for re-connection has been invalid and APP developers shall invoke Logout to log out and return to the login interface for re-login.
/// </summary>
/// <param name="jsonExtension">json Extension parameter (backup, not required now) </param>
/// <param name="handler">Callback function for automatic re-connection
* If the error code kNIMResExist is returned, it means that re-connection cannot be continued, and App developers shall invoke Logout to return to login interface, so that users can log in again.
/// </param>
public static void RegAutoReloginCb(LoginResultDelegate handler, string jsonExtension = null)

/// <summary>
/// Register the callback for offline status at NIM client
/// </summary>
/// <param name="handler">Callback function for being offline</param>
public static void RegDisconnectedCb(Action handler)

• Example

csharpprivate void RegisterAutoLoginCallback()
{
    NIM.ClientAPI.RegDisconnectedCb(OnDisconnected);
    NIM.ClientAPI.RegAutoReloginCb(OnAutoRelogin);
}

private void OnDisconnected()
{
    UnityEngine.Debug.Log("The network is disconnected and it has been offline");
}

private void OnAutoRelogin(NIMLoginResult result)
{
    UnityEngine.Debug.Log(string.Format("Automatic re-connection:{0}", result.Serialize()));
}

Logout

The application clients shall invoke SDK logout interface NIM.ClientAPI.Logout to log out/exit their accounts. The operation will notify CommsEase server to unbind APNS information to avoid logout of users, but Apple Push Notification service may be still sent to current device. Setting the correct NIMLogoutType parameter is required for calling Logout.

Notes: NIM.ClintAPI.Cleanup shall be executed to release resources when you log out the program. The function shall be executed in the callback for Logout to ensure invocation of Cleanup after the completion of Logout.

• API prototype

csharp/// <summary>
/// Log out of/exit NIM client
/// </summary>
/// <param name="logoutType">Logout Operation type</param>
/// <param name="delegate">Callback function for logout/exit.</param>
public static void Logout(NIMLogoutType logoutType, LogoutResultDelegate logoutDelegate)

• Parameter Description

logoutType	Application scene
kNIMLogoutChangeAccout	Log out/switch account, without exit the program
kNIMLogoutKickout	Be removed from other terminals to which a user also logs in
kNIMLogoutAppExit	Exit program

logoutDelegate: Logout executes the result callback without judging the returned error code.

• Example

csharpprivate void DoLogout()
{
    NIM.ClientAPI.Logout(NIM.NIMLogoutType.kNIMLogoutChangeAccout, OnAppLogoutCompleted);
}

private void OnAppLogoutCompleted(NIMLogoutResult result)
{
    UnityEngine.Debug.Log("switch account logout end:" + result.ToString());
    //If Cleanup shall be executed, it is necessary to ensure that Logout has been executed.
    //NIM.ClientAPI.Cleanup()
}

Multi-terminal Login

The interface NIM.ClientAPI.RegMultiSpotLoginNotifyCb is invoked to register the callback for multi-terminal login. When the login is successful, if login or logout occurs in other terminals, the callback function will send notifications to the client. The current online client type and OS can be acquired in the callback function.

• API prototype

csharp/// <summary>
/// Register the callback for notification of multi-point login at NIM client.
/// </summary>
/// <param name="handler">Callback function for notification of multi-point login.</param>
public static void RegMultiSpotLoginNotifyCb(MultiSpotLoginNotifyResultHandler handler)

• Example

csharpprivate void DoRegisgerMultiLoginNotify()
{
    NIM.ClientAPI.RegMultiSpotLoginNotifyCb(OnMultiLogin);
}
private void OnMultiLogin(NIMMultiSpotLoginNotifyResult result)
{
    //result.OtherClients - The list of client information is included.
    if(result.NotifyType == kNIMMultiSpotNotifyTypeImIn)
    {
        //Log in to other terminals
    }
    else if(result.NotifyType == kNIMMultiSpotNotifyTypeImOut)
    {
        //Log out of other terminals
    }
}

Login Policy

Built-in login policy in CommsEase: multual removal in mobile terminal (Android,iOS), mutual removal in desktop terminal (PC,Web), and login sessions on mobile and desktop terminals are valid (the interface NIM.ClientAPI.KickOtherClients can be invoked to actively remove other coexisted terminals). If the current kickout policy cannot satisfy business needs, contact us to cancel the built-in mutual kickout policy, and determine whether the current device needs to be kicked out according to the callback of multi-terminal login and the current device list. SDK provides the callback for notifying the event of being removed from other terminals.

• API prototype

csharp/// <summary>
/// The account is removed from other terminals. The result is acquired by registering the callback RegKickOtherClientCb.
/// </summary>
/// <param name="devices">Device ID</param>
public static void KickOtherClients(NIMKickoutOtherDeviceInfo devices)
/// <summary>
/// Register the result callback for removing the account from other terminals from NIM client
/// </summary>
/// <param name="handler">Callback function for operation results</param>
public static void RegKickOtherClientCb(KickOtherClientResultHandler handler)
/// <summary>
/// Register the callback for being removed from NIM client
/// </summary>
/// <param name="handler">Callback for being removed</param>
public static void RegKickoutCb(KickoutResultHandler handler)

• Parameter Description

In the function KickOtherClients, the device id parameter devices is the list of IDs of other devices under login status. The callback for login result and the callback for multi-terminal login include information of other devices under login status. The information includes device ID.

• Example

csharpprivate void RegisterKickoutCallback()
{
    //Register the callback for being removed
    NIM.ClientAPI.RegKickoutCb(OnKickedoutCallback);
}
private void OnKickedoutCallback(NIMKickoutResult result)
{
    UnityEngine.Debug.Log("OnKickedoutCallback");
    var tip = string.Format("Account removed:{0},{1}", result.ClientType, result.KickReason);
    UnityEngine.Debug.Log(tip);
}

//Remove a user from other terminals
private void DoKickOtherClients(NIMKickoutOtherDeviceInfo info)
{
    NIM.ClientAPI.RegKickOtherClientCb(OnKickOtherClients);
    NIM.ClientAPI.KickOtherClients(info);
}
private void OnKickOtherClients(NIMKickOtherResult result)
{
    string s = string.Empty;
    foreach (var d in result.DeviceIDs)
        s += (d + " ; ");
    UnityEngine.Debug.Log(string.Format("Operation results:{0},{1}", result.ResCode, s));
}

Login Status

Developers can invoke NIM.ClientAPI.GetLoginState() to actively get online status of current user.

• API prototype

csharp/// <summary>
/// Get login status of NIM client
/// </summary>
/// <param name="jsonExt"></param>
/// <returns></returns>
public static NIMLoginState GetLoginState(string jsonExt = null)

• Parameter Description

Login status	Description
kNIMLoginStateLogin	Login status for current account
kNIMLoginStateUnLogin	Non-login status for current account