Quick start

This guide describes how to integrate the SDK and implement a basic one-on-one voice call using ZEGOCLOUD's ZegoExpressEngine SDK.

Prerequisites

Before you begin, make sure you complete the following:

• Android Studio 2020.3.1 or later
• Android SDK Packages: Android SDK 25, Android SDK Build-Tools 25.0.2, Android SDK Platform-Tools 25.x.x or later.
• An Android device or Simulator that is running on Android 4.4 or later and supports audio and video. We recommend you use a real device.
• Sign up and create a project in Admin Console.

Create an Android project

Skip to this step if a project already exists.

Import the SDK

The Android ABIs currently supported by the SDK: armeabi-v7a, arm64-v8a, x86, x86_64.

Choose either of the following methods to integrate the ZEGO Express SDK into your project.

Implement voice call functions

Understand the tech

The following diagram shows the basic process of User A playing a stream published by User B:

For a better understanding, you can check the key concepts of ZegoExpressEngine SDK:

Sample code

Here is a downloadable demo code that can be used as a reference when developing your app.

1. Create & destroy the ZegoExpressEngine instance

call the createEngineWithProfile method to initialize the ZegoExpressEngine SDK. And config the following:

• profile: the ZegoEngineProfile object, used to config the appID and appSign, as well as the scenario you are applying the SDK to.
• eventHandler: an event handler object, used to listen for core event callbacks, such as the callback for updates on the room connection stats changes, updates on in-room participants log in or log out, and more. You can call the setEventHandler method to set up the event handler object.

To destroy the SDK and release the resources it occupies, call the destroy method.

void createEngine() {
    ZegoEngineProfile profile = new ZegoEngineProfile();

    // Get your AppID and AppSign from ZEGOCLOUD Console
    //[My Projects -> AppID] : https://console.zegocloud.com/project
    profile.appID = appID;
    profile.appSign = appSign;
    profile.scenario = ZegoScenario.DEFAULT; // General scenario.
    profile.application = getApplication();
    ZegoExpressEngine.createEngine(profile, null);
}


// destroy engine
private void destroyEngine() {
    ZegoExpressEngine.destroyEngine(null);
}

2. Set up an event handler

Implement the ZegoEventHandler event handler to listen for event callbacks, such as the event callback on the updates when the in-room streams are added or deleted, the updates when in-room participants log in or log out, the updates when room connection state changes, and more.

• onRoomStreamUpdate: Callback for updates on the status of the streams in the room. When new streams are published to the room or existing streams in the room stop, the SDK sends out the event notification through this callback. You can call startPlayStream() and stopPlayStream() methods in this callback.

• onRoomStateUpdate: Callback for updates on current room connection status. When the current room connection status changes (for example, when the current user is disconnected from the room or login authentication fails), the SDK sends out the event notification through this callback.

• onRoomUserUpdate: Callback for updates on the status of other users in the room. When other users log in or log out of the room, the SDK sends out the event notification through this callback.

void startListenEvent() {
    ZegoExpressEngine.getEngine().setEventHandler(new IZegoEventHandler() {
        @Override
        // Callback for updates on the status of the streams in the room.
        public void onRoomStreamUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoStream> streamList, JSONObject extendedData) {
            super.onRoomStreamUpdate(roomID, updateType, streamList, extendedData);
            // When `updateType` is set to `ZegoUpdateType.ADD`, an audio and video
            // stream is added, and you can call the `startPlayingStream` method to
            // play the stream.
            if (updateType == ZegoUpdateType.ADD) {
                startPlayStream(streamList.get(0).streamID);
            } else {
                stopPlayStream(streamList.get(0).streamID);
            }
        }

        @Override
        // Callback for updates on the status of other users in the room.
        // Users can only receive callbacks when the isUserStatusNotify property of ZegoRoomConfig is set to `true` when logging in to the room (loginRoom).
        public void onRoomUserUpdate(String roomID, ZegoUpdateType updateType, ArrayList<ZegoUser> userList) {
            super.onRoomUserUpdate(roomID, updateType, userList);
            // You can implement service logic in the callback based on the login
            // and logout status of users.
            if (updateType == ZegoUpdateType.ADD) {
                for (ZegoUser user : userList) {
                    String text = user.userID + "logged in to the room.";
                    Toast.makeText(getApplicationContext(), text, Toast.LENGTH_LONG).show();
                }
            } else if (updateType == ZegoUpdateType.DELETE) {
                for (ZegoUser user : userList) {
                    String text = user.userID + "logged out of the room.";
                    Toast.makeText(getApplicationContext(), text, Toast.LENGTH_LONG).show();
                }
            }
        }

        @Override
        // Callback for updates on the current user's room connection status.
        public void onRoomStateChanged(String roomID, ZegoRoomStateChangedReason reason, int i, JSONObject jsonObject) {
            super.onRoomStateChanged(roomID, reason, i, jsonObject);
            if (reason == ZegoRoomStateChangedReason.LOGIN_FAILED) {
                Toast.makeText(getApplicationContext(), "ZegoRoomStateChangedReason.LOGIN_FAILED", Toast.LENGTH_LONG).show();
            }
        }

        // Status notification of audio and video stream publishing.
        @Override
        public void onPublisherStateUpdate(String streamID, ZegoPublisherState state, int errorCode, JSONObject extendedData) {
            super.onPublisherStateUpdate(streamID, state, errorCode, extendedData);
            if (errorCode != 0) {
                // Stream publishing exception.
            }
            if (state == ZegoPublisherState.PUBLISHING) {
                // Publishing streams.
            } else if (state == ZegoPublisherState.NO_PUBLISH) {
                // Streams not published.
                Toast.makeText(getApplicationContext(), "ZegoPublisherState.NO_PUBLISH", Toast.LENGTH_LONG).show();
            } else if (state == ZegoPublisherState.PUBLISH_REQUESTING) {
                // Requesting stream publishing.
            }
        }

        // Status notifications of audio and video stream playing.
        @Override
        public void onPlayerStateUpdate(String streamID, ZegoPlayerState state, int errorCode, JSONObject extendedData) {
            super.onPlayerStateUpdate(streamID, state, errorCode, extendedData);
            if (errorCode != 0) {
                // Stream playing exception.
                Toast.makeText(getApplicationContext(), "onPlayerStateUpdate, state:" + state + "errorCode:" + errorCode, Toast.LENGTH_LONG).show();
            }
            if (state == ZegoPlayerState.PLAYING) {
                // Playing streams.
            } else if (state == ZegoPlayerState.NO_PLAY) {
                // Streams not played.
                Toast.makeText(getApplicationContext(), "ZegoPlayerState.NO_PLAY", Toast.LENGTH_LONG).show();
            } else if (state == ZegoPlayerState.PLAY_REQUESTING) {
                // Requesting stream playing.
            }
        }
    });
}

void stopListenEvent() {
    ZegoExpressEngine.getEngine().setEventHandler(null);
}

3. Log in & log out

To log in to a room, you can call the loginRoom method.

To log out, you can call the logoutRoom method.

void loginRoom() {
    ZegoUser user = new ZegoUser(userID, userName);
    ZegoRoomConfig roomConfig = new ZegoRoomConfig();
    // The `onRoomUserUpdate` callback can be received only when
    // `ZegoRoomConfig` in which the `isUserStatusNotify` parameter is set to
    // `true` is passed.
    roomConfig.isUserStatusNotify = true;
    ZegoExpressEngine.getEngine().loginRoom(roomID, user, roomConfig, (int error, JSONObject extendedData) -> {
        // Room login result. This callback is sufficient if you only need to
        // check the login result.
        if (error == 0) {
            // Login successful.
            // Start the preview and stream publishing.
            Toast.makeText(this, "Login successful.", Toast.LENGTH_LONG).show();
            startPreview();
            startPublish();
        } else {
            // Login failed. For details, see [Error codes\|_blank](/404).
            Toast.makeText(this, "Login failed. error = " + error, Toast.LENGTH_LONG).show();
        }
    });
}

void logoutRoom() {
    ZegoExpressEngine.getEngine().logoutRoom();
}

4. Start & stop publishing streams

To start publishing a local audio or video stream to remote users, call the startPublishingStream method.

And you can call the stopPublishingStream method to stop the stream publishing.

void startPublish() {
    // After calling the `loginRoom` method, call this method to publish streams.
    // The StreamID must be unique in the room.
    String streamID = roomID + "_" + userID + "_call";
    ZegoExpressEngine.getEngine().enableCamera(false);
    ZegoExpressEngine.getEngine().startPublishingStream(streamID);
}


void stopPublish() {
    ZegoExpressEngine.getEngine().stopPublishingStream();
}

6. Start & stop playing streams

You can call startPlayingStream method to start playing a remote video stream.

And to stop the stream playing, call the stopPlayingStream method to stop.

void startPlayStream(String streamID){
    ZegoExpressEngine.getEngine().startPlayingStream(streamID);
}

void stopPlayStream(String streamID){
    ZegoExpressEngine.getEngine().stopPlayingStream(streamID);
    findViewById(R.id.remoteUserView).setVisibility(View.GONE);
}

Start and stop your app

When your app starts, you need to call the createEngine method to initialize the SDK. When your app is about to exit, you can call the destroyEngine to release SDK resources.

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    createEngine();
    initViews();
}

@Override
protected void onDestroy() {
    super.onDestroy();
    destroyEngine();
}

Configure your project

Add device permissions

Permissions can be set as needed.

Open the file app/src/main/AndroidManifest.xml, and add the following code:

<!-- Permissions required by the SDK -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

<!-- Permissions required by the App -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true" />

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />

Note: For Android 6.0 or later, some important permissions must be requested at runtime rather than declared statically in the file AndroidMainfest.xml, therefore, you need to add the following code to do so (requestPermissions is a method of an Android Activity).

String[] permissionNeeded = {
    "android.permission.CAMERA",
    "android.permission.RECORD_AUDIO"};

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    if (ContextCompat.checkSelfPermission(this, "android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED ||
        ContextCompat.checkSelfPermission(this, "android.permission.RECORD_AUDIO") != PackageManager.PERMISSION_GRANTED) {
        requestPermissions(permissionNeeded, 101);
    }
}

Prevent class name obfuscation

To prevent the ZEGO SDK public class names from being obfuscated, you can add the following code in the file proguard-rules.pro.

-keep class **.zego.**{*;}

Test your implementation

To test your implementation, run your app project on a real device.

For your convenience of testing experience, we got you a Web platform for debugging. On the debugging page, you can enter the AppID and room ID of the real device user, and a different user ID to log in to the same room for communicating with the real device user. After a voice call starts successfully, you can hear the remote audio and view the remote video.