Menu

Android

Last updated: 2023-09-21 15:37:01Download PDF
This document describes how to quickly integrate the TUICallKit component. Performing the following key steps generally takes about an hour, after which you can implement the video call feature with complete UIs.

Environment Preparations

Android 4.1 (SDK API level 16) or later (Android 5.0 (SDK API level 21) or later is recommended).
Android Studio 3.5 or later (Gradle 3.5.4 or later).
Mobile phone on Android 4.1 or later.


Step 1. Activate the service

TUICallKit is an audio & video communication component built upon Tencent Cloud's paid PaaS services, Chat and Real-time Communication (TRTC) . In order for you to better experience the Call feature, we offer a 7-day free trial version for each SDKAppID (Note: no additional call duration is provided with the free trial version), You can activate the Call free trial version in the (Real-time Communication)TRTC console, with the specific operation steps as follows:

1. Log into the TRTC console > Call, and create a new application.

2. In the create pop-up window, select Call as the product and enter the application name. You can also choose to associate with an existing application to open Call for an existing TRTC application. After making the selection, click on Create application.

3. After completing the application creation, you will be directed to the application details page by default. In the pop-up window, select the "Trial Free" version and click on "Claim now".

4. After confirming the pop-up content, click on "Free Trail" to successfully open the trial version of audio and video calling.

5. After opening, you can view the version information on the current page and refer to the integration guide for integration.


Step 2. Download and import the component

Go to GitHub, clone or download the code, and copy the tuicallkit subdirectory in the Android directory to the directory at the same level as app in your current project, as shown below:

img



Step 3. Configure the project

1. Find the settings.gradle file in the project root directory and add the following code to import the TUICallKit component downloaded in step 2 to your current project:
include ':tuicallkit'
2. Find the build.gradle file in the app directory and add the following code to declare the dependencies of the current application on the TUICallKit component just added:
api project(':tuicallkit')
Note
The TUICallKit project depends on TRTC SDK, Chat SDK, tuicallengine, and the tuicore public library internally by default with no need of additional configuration. To upgrade the version, modify the tuicallkit/build.gradle file.
3. As the SDK uses Java's reflection feature internally, you need to add certain classes in the SDK to the obfuscation allowlist by adding the following code to the proguard-rules.pro file:
-keep class com.tencent.** { *;}
Note
TUICallKit helps you apply for camera, mic, and storage read/write permissions internally. If you need more or fewer permissions based on your actual business conditions, you can modify tuicallkit/src/main/AndroidManifest.xml.

Step 4. Log in to the TUICallKit component

Add the following code to your project to call the relevant APIs in TUICore to log in to the TUICallKit component. This step is very important, as the user can use the component features properly only after a successful login. Carefully check whether the relevant parameters are correctly configured:
// Set the listener for the login result
private final TUILoginListener mLoginListener = new TUILoginListener() {
@Override
public void onKickedOffline() {
super.onKickedOffline();
Log.i(TAG, "You have been kicked off the line. Please login again!");
//logout();
}
@Override
public void onUserSigExpired() {
super.onUserSigExpired();
Log.i(TAG, "Your user signature information has expired");
//logout();
}
};
TUILogin.addLoginListener(mLoginListener);

// Log in
TUILogin.login(context,
1400000001, // Replace it with the `SDKAppID` obtained in step 1.
"denny", // Replace it with your `UserID`.
"xxxxxxxxxxx", // You can calculate a `UserSig` in the console and enter it here.
new TUICallback() {
@Override
public void onSuccess() {
Log.i(TAG, "login success");
}

@Override
public void onError(int errorCode, String errorMessage) {
Log.e(TAG, "login failed, errorCode: " + errorCode + " msg:" + errorMessage);
}
});
Parameter description: The key parameters used by the login function are as detailed below:
SDKAppID: Obtained in the last step in step 1 and not detailed here.
UserID: The ID of the current user, which is a string that can contain only letters (a–z and A–Z), digits (0–9), hyphens (-), or underscores (_).
UserSig: The authentication credential used by Tencent Cloud to verify whether the current user is allowed to use the TRTC service. You can get it by using the SecretKey to encrypt the information such as SDKAppID and UserID. You can generate a temporary UserSig by clicking the UserSig generation button in the console.

For more information, see UserSig.
Note
Many developers have contacted us with questions regarding this step. Below are some of the frequently encountered problems:

SDKAppID is invalid.
userSig is set to the value of Secretkey mistakenly. The userSig is generated by using the SecretKey for the purpose of encrypting information such as sdkAppId, userId, and the expiration time. But the value of the userSig that is required cannot be directly substituted with the value of the SecretKey.
userId is set to a simple string such as 1, 123, or 111, and your colleague may be using the same userId while working on a project simultaneously. In this case, login will fail as TRTC doesn't support login on multiple terminals with the same UserID. Therefore, we recommend you use some distinguishable userId values during debugging.

The sample code on GitHub uses the genTestUserSig function to calculate UserSig locally, so as to help you complete the current integration process more quickly. However, this scheme exposes your SecretKey in the application code, which makes it difficult for you to upgrade and protect your SecretKey subsequently. Therefore, we strongly recommend you run the UserSig calculation logic on the server and make the application request the UserSig calculated in real time every time the application uses the TUICallKit component from the server.

Step 5. Make a call

One-to-one video call

You can call the call function of TUICallKit and specify the call type and the callee's userId to make an audio/video call.
// Make a one-to-one video call. Suppose the `UserID` is `mike`.
TUICallKit.createInstance(context).call("mike", TUICallDefine.MediaType.Video);
Parameter
Type
Description
userId
String
The ID of the target user, such as "mike".
callMediaType
TUICallDefine.MediaType
The call media type, such as TUICallDefine.MediaType.Video.

Group video call

You can call the groupCall function of TUICallKit and specify the call type and the list of callee's UserID values to make a group audio/video call.
TUICallKit.createInstance(context).groupCall("12345678", Arrays.asList("jane", "mike", "tommy"),TUICallDefine.MediaType.Video);
Parameter
Type
Description
groupId
String
The group ID, such as "12345678".
userIdList
List
The list of UserID values of the target users, such as {"jane", "mike", "tommy"}.
callMediaType
TUICallDefine.MediaType
The call media type, such as TUICallDefine.MediaType.Video.
Note
You can create a group as instructed in Android, iOS, and macOS. You can also use Chat TUIKit to integrate chat and call scenarios at one stop.
TUICallKit currently doesn't support making a multi-person video call among users not in a group. If you have such a need, contact colleenyu@tencent.com.

Step 6. Answer a call

After receiving an incoming call, the TUICallKit component will automatically wake up the call answering UI. However, the wake effect varies by Android system permissions as follows:
If your application is in the foreground, it will pop up the call UI and play back the incoming call ringtone automatically when receiving an incoming call.
If your application is in the background and is granted the Display over other apps or Display pop-up windows while running in the background permission, it will still pop up the call UI and play back the incoming call ringtone automatically when receiving an incoming call.
If your application is in the background but isn't granted with the Display over other apps or Display pop-up windows while running in the background permission, TUICallKit will play back the incoming call ringtone to prompt the user to answer or decline the call.
If the application process has been terminated, you can use the offline push feature as described in Offline Call Push (Android) to prompt the user to answer or decline the call through the status bar notification.


Step 7. Implement more features

1. Nickname and profile photo settings

To customize the nickname or profile photo, use the following API for update:
TUICallKit.createInstance(context).setSelfInfo("jack", "https:/****/user_avatar.png", callback);
Note
The update of the callee's nickname and profile photo may be delayed during a call between non-friend users due to the user privacy settings. After a call is made successfully, the information will also be updated properly in subsequent calls.

2. Offline call push

You can make/answer audio or video calls after completing the above steps. However, if you want your users to be able to receive call invitations even when your application is in the background or after it is closed, then you need to also implement the offline call push feature. For more information, see Offline Call Push (Android).

3. Floating window

To implement the floating window feature in your application, call the following API when initializing the TUICallKit component:
TUICallKit.createInstance(context).enableFloatWindow(true);

4. Call status listening

To listen on the call status (for example, the start or end of a call or the call quality during a call), listen on the following events:
TUICallEngine.createInstance(context).addObserver(new TUICallObserver() {
@Override
public void onCallBegin(TUICommonDefine.RoomId roomId, TUICallDefine.MediaType callMediaType, TUICallDefine.Role callRole) {
}
public void onCallEnd(TUICommonDefine.RoomId roomId, TUICallDefine.MediaType callMediaType,TUICallDefine.Role callRole, long totalTime) {
}
public void onUserNetworkQualityChanged(List<TUICommonDefine.NetworkQualityInfo> networkQualityList) {
}
});

private void initData(){
TUICallEngine.createInstance(mContext).addObserver(mTUICallObserver);
}
Note:
When you set TUICallObserver to observer the call, ensure that the class to which the observer belongs is not cleared. For example, you are not advised to add a observer to LoginActivity. When LoginActivity is destroyed, the observer will also be cleared. You are advised to add the observer in the application class.

5. Custom ringtone

You can use the following API to customize the ringtone:
TUICallKit.createInstance(context).setCallingBell(filePath);

6. Custom call timeout period

You can set callParams when invoke call, groupCall,inviterUser to change your call timeout period.
TUICallDefine.CallParams params = new TUICallDefine.CallParams();
params.offlinePushInfo = OfflinePushInfoConfig.createOfflinePushInfo(mContext);
params.timeout = 30;
params.userData = "user data";

TUICallEngine.createInstance(mContext).call(roomId, userId, mediaType, params, null);

FAQs

1. What should I do if I receive the error message "The package you purchased does not support this ability"?

The error message indicates that your application's audio/video call capability package has expired or is not activated. You can claim or activate the audio/video call capability as instructed in step 1 to continue using TUICallKit.

2、How to purchase official version?

please refer to Purchase Official Version.

3. What should I do if TUICallKit crashes and outputs the log "No implementation found for xxxx"?

Below is the stack information:
java.lang.UnsatisfiedLinkError: No implementation found for void com.tencent.liteav.base.Log.nativeWriteLogToNative(int, java.lang.String, java.lang.String) (tried Java_com_tencent_liteav_base_Log_nativeWriteLogToNative and Java_com_tencent_liteav_base_Log_nativeWriteLogToNative__ILjava_lang_String_2Ljava_lang_String_2)
at com.tencent.liteav.base.Log.nativeWriteLogToNative(Native Method)
at com.tencent.liteav.base.Log.i(SourceFile:177)
at com.tencent.liteav.basic.log.TXCLog.i(SourceFile:36)
at com.tencent.liteav.trtccalling.model.impl.base.TRTCLogger.i(TRTCLogger.java:15)
at com.tencent.liteav.trtccalling.model.impl.ServiceInitializer.init(ServiceInitializer.java:36)
at com.tencent.liteav.trtccalling.model.impl.ServiceInitializer.onCreate(ServiceInitializer.java:101)
at android.content.ContentProvider.attachInfo(ContentProvider.java:2097)
at android.content.ContentProvider.attachInfo(ContentProvider.java:2070)
at android.app.ActivityThread.installProvider(ActivityThread.java:8168)
at android.app.ActivityThread.installContentProviders(ActivityThread.java:7709)
at android.app.ActivityThread.handleBindApplication(ActivityThread.java:7573)
at android.app.ActivityThread.access$2600(ActivityThread.java:260)
at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2435)
at android.os.Handler.dispatchMessage(Handler.java:110)
at android.os.Looper.loop(Looper.java:219)
at android.app.ActivityThread.main(ActivityThread.java:8668)
at java.lang.reflect.Method.invoke(Native Method)
at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:513)
at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:1109)
TUICallkit is not supported on VMs and must be run on a real device. If the above exception occurs on a real device, it is because some APIs of SDKs such as the TRTC SDK depended on by TUICallKit are implemented through JNI, but Android Studio may not package native .so libraries when compiling the APK under some conditions. In this case, just clean the project again.

Suggestions and Feedback

If you have any suggestions or feedback, please contact colleenyu@tencent.com.