Hyphenate Docs

Start Chatting with Hyphenate!

Welcome to the Hyphenate docs portal. Here you'll find comprehensive guides and technical documentation to help you integrate Hyphenate In-App Chat.

Get Started

Basic Operations

Initialize the SDK

EMOptions options = new EMOptions();
// Contact invitation: The default, it does not ask for verification.
options.setAcceptInvitationAlways(false);
...
// Initialize the SDK.
EMClient.getInstance().init(applicationContext, options);
// During proguard, turn off the debug mode to reduce resource consumption.
EMClient.getInstance().setDebugMode(true);

EMOption - Auto login

Auto login bypasses the login process if the user has logged in successfully in a previous session. The attribute of auto login is true by default.

options.setAutoLogin(false);

Auto login will be canceled under the following situations:

  • The logout method is called and executed from a previous session
  • The user's credential or password is changed and causes auto-login failure
  • The user account is deleted from the server
  • The user logs into another device and the system forces the user to logout on their current device, since it only supports login on a single mobile device.

3rd-party Service

In order to enable the third-party service for your Android app, add the following method before the EMClient.getInstance().init(applicationContext, options) call to initialize the SDK.

appContext = this;
int pid = android.os.Process.myPid();
String processAppName = getAppName(pid);

// If the remote service is enabled application::OnCreate would be called twice.
// To prevent the Hyphenate SDK from initialized multiple times, add this if-else clause to initialize the SDK at the first time.
// By default, process name is equal to the package name. If the process name is inconsistent with the app’s process name, the app will return immediately.

if (processAppName == null ||!processAppName.equalsIgnoreCase(appContext.getPackageName())) {
    Log.e(TAG, "enter the service process!");

    // Otherwise, the application::onCreate is called by the service and the application should return directly.
    return;
}

Get the processAppName

private String getAppName(int pID) {
    String processName = null;
    ActivityManager am = (ActivityManager) this.getSystemService(ACTIVITY_SERVICE);
    List l = am.getRunningAppProcesses();
    Iterator i = l.iterator();
    PackageManager pm = this.getPackageManager();
    while (i.hasNext()) {
        ActivityManager.RunningAppProcessInfo info = (ActivityManager.RunningAppProcessInfo) (i.next());
        try {
            if (info.pid == pID) {
                CharSequence c = pm.getApplicationLabel(pm.getApplicationInfo(info.processName, PackageManager.GET_META_DATA));
                // Log.d("Process", "Id: " + info.pid + " ProcessName: " + info.processName + " Label: " + c.toString());
                // processName = c.toString();
                processName = info.processName;
                return processName;
            }
        } catch (Exception e) {
            // Log.d("Process", "Error>> :"+ e.toString());
        }
    }
    return processName;
}

Register a New Account

We recommend you register new Hyphenate accounts via REST API, but you can also do it from the client SDK.

EMClient.getInstance().createAccount(username, pwd);

Login

EMClient.getInstance().login(userName, password, new EMCallBack() {//callback
    @Override
    public void onSuccess() {
            // Login the IM server successfully

            // Load All Conversations and Groups
            EMClient.getInstance().groupManager().loadAllGroups();
        EMClient.getInstance().chatManager().loadAllConversations();
    }

    @Override
    public void onProgress(int progress, String status) {
            // show ui loading indicator    
    }

    @Override
    public void onError(int code, String message) {
        // Failed to login the IM server
    }
});

Auto login

Auto login is to log the user into the Hyphenate server automatically without triggering the login method again after a successful login. The attribute of auto login is set to YES by default in the SDK. You can adjust the auto login by changing the setting 'successful login'.

options.setAutoLogin(false);

Auto login will be canceled under the following situations:

  • The logout method is called and executed from a previous session
  • The user's credential or password is changed and causes an auto-login failure
  • The user account is deleted from the server
  • The user logs into another device and the system forces the user to logout of their current device, since it only supports login on a single mobile device.

Load All Conversations and Groups

Call the following methods after logging into the Hyphenate server successfully to ensure that the app loads the local conversations and groups. If the user already logged in within a previous session and enters the foreground, then call those two methods in the main page’s onCreate method to load the conversations and groups, or call the methods before the app enters the foreground.

EMClient.getInstance().groupManager().loadAllGroups();
EMClient.getInstance().chatManager().loadAllConversations();

Logout

There are two types of logout scenarios,

Active logout:

Active logout is when you call the logout method explicitly.

Pass true to logout method if integrated with GCM to unbind the token, otherwise it'll cause the issue of receiving push notifications even if the user is already logged out.
If failed to unbind the token due to the Internet connection issue, it will either prevent the logout process or warn the user that it's still possible to receive push notifications and pass false to logout method.

Synchronous method

EMClient.getInstance().logout(true);

Asynchronous method

EMClient.getInstance().logout(true, new EMCallBack() {

    @Override
    public void onSuccess() {
        // logout succeed, handle the logged out UI
    }

    @Override
    public void onProgress(int progress, String status) {
        // handle the logging out UI
    }

    @Override
    public void onError(int code, String message) {
        // handle logout error
    }
});

Passive logout

Passive logout is triggered if a user is forced logout by the developer via REST API or console, exceeding the login session limitation, or a user is deleted from the system, etc.

Connection Status Changed

The SDK will attempt to reconnect automatically if the device connection dropped due to a network issue.

Turn off the automatic reconnection

options.setAutoLogin(false)

The SDK provides a connection status listener for you to listen to the connection status in realtime.

There is error info to help with identifying the cause of disconnection.

EMError.USER_LOGIN_ANOTHER_DEVICE     // the account has logged in on another device. 
EMError.USER_REMOVED                  // the account has been removed from the backend.

// Register for a connection status listener
EMClient.getInstance().addConnectionListener(new MyConnectionListener());

// Implement ConnectionListener
private class MyConnectionListener implements EMConnectionListener {
    @Override
    public void onConnected() {
    }
    @Override
    public void onDisconnected(final int error) {
        runOnUiThread(new Runnable() {

            @Override
            public void run() {
                if (error == EMError.USER_REMOVED){
                    // The account has been removed
                }
                                else if (error == EMError.USER_LOGIN_ANOTHER_DEVICE) {
                    // The account has logged in on another device
                } 
                                else {
                        if (NetUtils.hasNetwork(MainActivity.this))
                    // The IM server is disconnected
                else
                    // The network is unavailable. Please check the network settings.
                }
            }
        });
    }
}

Next Step: Messages

Basic Operations


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.