please select
  • UIKit
  • SDK
  • Server APIs
Chat/
SDK/
Android/
SDK
  • Install Chat SDK
  • Initialize Chat SDK
  • Login and Logout
  • Message
    • Overview
    • Send a Message
    • Receive a Message
    • Retrieve Messages
    • Forward Messages
    • Modify a Message
    • Insert a Message
    • Delete Messages
    • Clear History Messages
    • Recall a Message
    • Send an Online Message
    • Message Read Receipt
    • Query Messages
    • Mentions
    • Targeted Group Message
    • Do not Notify
    • Key-Value Extensions
    • Reactions
    • Translation
    • Pin Messages
  • Conversation
    • Overview
    • Conversation List
    • Get Conversations
    • Unread Count
    • Pin Conversations
    • Delete Conversations
    • Draft
    • Mark
    • Conversation Group
  • Group
    • Overview
    • Manage Group
    • Profile
    • Manage Members
    • Member Profile
    • Attribute
    • Counter
  • Community and Topic
    • Manage Community
    • Permission Group
  • User
    • User Profile
    • User Status
    • Manage Friends
    • Friend Group
    • Block Lists
    • Follow
  • Local Search
    • Search Messages
    • Search Friends
    • Search Groups
    • Search Group Members
  • Signaling
  • API Reference
    • Java
  • Guideline for Beginners
  • Console Guide
    • Creating and Upgrading an Application
    • Basic Configuration
    • Feature Configuration
    • Account Management
    • Group Management
    • Webhook Configuration
  • Product Introduction
    • Message Management
      • One-to-One Message
      • Message Storage
      • Offline Push
      • Group Message
      • Message Formats
    • Account System
      • Login Authentication
      • Online Status Management
    • Group Related
      • Group System
      • Group Management
    • User Profile and Relationship Chain
      • Profile Management
      • Relationship Chain Management
  • Purchase Guide
    • Billing Overview
    • Pricing
  • Error Codes

Initialize Chat SDK

Feature Description

You must initialize the SDK before using its features. In most scenarios, you need to initialize the SDK only once during the application lifecycle.

Initialization

You can initialize the SDK in the following steps:
1. Prepare an SDKAppID.
2. Configure the V2TIMSDKConfig object.
3. Add an SDK event listener.
4. Call initSDK to initialize the SDK.
The detailed steps are as follows.

Preparing an SDKAppID

SDKAppID uniquely identifies an account. We recommend you apply for a new SDKAppID for each application. Messages are naturally isolated and cannot communicate between different SDKAppID values. To perform the initialization, you must have a correct SDKAppID. In the Chat Console, you can view all your SDKAppID values, and you can click Create Application to create an SDKAppID.



Configuring the V2TIMSDKConfig

Before initializing the SDK, you need to initialize the V2TIMSDKConfig object (Android / iOS and macOSWindows), which is used to configure the SDK initially, such as setting the log level and log listening callback.

Setting the log level

The SDK supports the following log levels:
Log Level
Log Output
V2TIM_LOG_NONE
No log is output.
V2TIM_LOG_DEBUG
Logs at the DEBUG, INFO, WARNING, and ERROR levels are output (default log levels).
V2TIM_LOG_INFO
Logs at the INFO, WARNING, and ERROR levels are output.
V2TIM_LOG_WARN
Logs at the WARNING and ERROR levels are output.
V2TIM_LOG_ERROR
Logs at the ERROR level are output.
SDK log storage rules are as follows:
Local SDK logs are retained for seven days by default, after which the logs will be automatically cleared during the SDK initialization.
By default, SDK logs on Android are stored in the /sdcard/tencent/imsdklogs/application package name directory for versions earlier than v4.8.50 and in the /sdcard/Android/data/package name/files/log/tencent/imsdk directory for v4.8.50 or later.
By default, SDK logs on iOS are stored in the /Library/Caches/com_tencent_imsdk_log directory.
By default, SDK logs on Windows are stored in the program's running directory. For example, when the program is running in the C:\App directory, SDK will store logs in the C:\App\com_tencent_imsdk_log directory.

Starting from v4.7.1, the xlog module from WeChat is used to output SDK logs, which are compressed by default and must be decompressed by using the Python script.
To obtain the script for decompression, click Decode Log 27 (for Python 2.7) or Decode Log 30 (for Python 3.0).
In the Windows or macOS console, you can decompress log files by running the following command. After decompression, the file names end with "xlog.log", and you can use the text editor to open these files.
python decode_mars_nocrypt_log_file.py imsdk_yyyyMMdd.xlog

Setting a log listener

If you need to listen on SDK logs in real time, you can call setLogListener (Android / iOS and macOSWindows) to set a log listener. After it is set, the SDK will throw log information through this callback in real time.
Note:
The callback is in the main thread. Log callbacks can be quite frequent, so be careful not to synchronize too many time-consuming tasks in the callback, which may block the main thread.
The sample code of configuring V2TIMSDKConfig is as follows:
Android
iOS and macOS
Windows
// Initialize the `config` object
V2TIMSDKConfig config = new V2TIMSDKConfig();
// Specify the log output level
config.setLogLevel(V2TIMSDKConfig.V2TIM_LOG_INFO);
// Specify the log listener
config.setLogListener(new V2TIMLogListener() {
@Override
public void onLog(int logLevel, String logContent) {
// `logContent` is the SDK log content
}
});
// Initialize the `config` object
V2TIMSDKConfig *config = [[V2TIMSDKConfig alloc] init];
// Specify the log output level
config.logLevel = V2TIM_LOG_INFO;
// Set the log listener
config.logListener = ^(V2TIMLogLevel logLevel, NSString *logContent) {
// `logContent` is the SDK log content
};
class LogListener final : public V2TIMLogListener {
public:
LogListener() = default;
~LogListener() override = default;
void OnLog(V2TIMLogLevel logLevel, const V2TIMString& logContent) override {
// `logContent` is the SDK log content
}
};
// Note that `logListener` should not be released before the SDK is uninitialized,
// otherwise the log callback cannot be called.
LogListener logListener;

// Initialize the `config` object
V2TIMSDKConfig config;
// Specify the log output level
config.logLevel = V2TIMLogLevel::V2TIM_LOG_INFO;
// Specify the log listener
config.logListener = &logListener;

Adding an SDK event listener

After the initialization, the SDK will report such events as connection status and login ticket expiration through V2TIMSDKListener. We recommend you call the addIMSDKListener API (Android / iOS and macOSWindows) to add an SDK event listener and perform logic processing in the corresponding callback.
V2TIMSDKListener callbacks are as follows:
Event Callback
Description
Recommended Operation
onConnecting
The SDK is connecting to the CVM instance.
Display the "connecting" status on the UI.
onConnectSuccess
The SDK is successfully connected to the CVM instance.
-
onConnectFailed
The SDK failed to connect to the CVM instance.
Notify the user that the network connection is currently unavailable.
onKickedOffline
The current user is kicked offline.
Display the "You are already logged in on another device. Are you sure you want to log in again?" message on the UI.
onUserSigExpired
The login ticket expired.
Log in with a new UserSig.
onSelfInfoUpdated
The current user's profile is updated.
Update the profile photo and nickname on the UI.
Note:
If you receive the onUserSigExpired callback, the UserSig that you use for login has expired. In this case, you need to use a new UserSig to log in again. If you continue to use the expired UserSig, the SDK will be in an infinite login loop.
Sample code:
Android
iOS and macOS
Windows
// The `sdkListener` type is `V2TIMSDKListener`.
V2TIMManager.getInstance().addIMSDKListener(sdkListener);
// The `self` type is id<V2TIMSDKListener>.
[[V2TIMManager sharedInstance] addIMSDKListener:self];
// `sdkListener` is an instance of V2TIMSDKListener.
V2TIMManager::GetInstance()->AddSDKListener(&sdkListener);

Calling the initialization API

After performing the above steps, you can call initSDK (Android / iOS and macOSWindows) to initialize the SDK.
Sample code:
Android
iOS and macOS
Windows
// 1. Get the `SDKAppID` from the IM console.
// 2. Initialize the `config` object.
V2TIMSDKConfig config = new V2TIMSDKConfig();
// 3. Specify the log output level.
config.setLogLevel(V2TIMSDKConfig.V2TIM_LOG_INFO);
// 4. Add the `V2TIMSDKListener` event listener. `sdkListener` is the implementation class of `V2TIMSDKListener`. If you don't need to listen to SDK events, skip this step.
V2TIMManager.getInstance().addIMSDKListener(sdkListener);
// 5. Initialize the SDK. You can call the login API as soon as you call this API.
int sdkAppID = 1400000000; // please set the sdkAppID of your own application
V2TIMManager.getInstance().initSDK(context, sdkAppID, config);
// 1. Get the `SDKAppID` from the IM console.
// 2. Initialize the `config` object.
V2TIMSDKConfig *config = [[V2TIMSDKConfig alloc] init];
// 3. Specify the log output level.
config.logLevel = V2TIM_LOG_INFO;
// 4. Add the `V2TIMSDKListener` event listener. `self` is the implementation class of id<V2TIMSDKListener>. If you don't need to listen to SDK events, skip this step.
[[V2TIMManager sharedInstance] addIMSDKListener:self];
// 5. Initialize the SDK. You can call the login API as soon as you call this API.
int sdkAppID = 1400000000; // please set the sdkAppID of your own application
[[V2TIMManager sharedInstance] initSDK:sdkAppID config:config];
// 1. Get the `SDKAppID` from the IM console.
// 2. Initialize the `config` object.
V2TIMSDKConfig config;
// 3. Specify the log output level.
config.logLevel = V2TIMLogLevel::V2TIM_LOG_INFO;
// 4. Add the `V2TIMSDKListener` event listener. `sdkListener` is the implementation class of `V2TIMSDKListener`.
// If you don't need to listen to SDK events, skip this step.
V2TIMManager::GetInstance()->AddSDKListener(&sdkListener);
// 5. Initialize the SDK. You can call the login API as soon as you call this API.
int sdkAppID = 1400000000; // please set the sdkAppID of your own application
V2TIMManager::GetInstance()->InitSDK(sdkAppID, config);

Uninitialization

Generally, if your application's lifecycle is the same as the SDK's lifecycle, you don't need to uninitialize the SDK before exiting the application. However, you can uninitialize the SDK in special cases, for example, only after you enter a specific UI and no longer use it after exiting the UI.
Uninitialization requires two steps:
1. If you have called addIMSDKListener to add the SDK listener, call removeIMSDKListener (Android / iOS and macOSWindows) to remove it.
2. Call the unInitSDK uninitialization API (Android / iOS and macOSWindows).
Sample code:
Android
iOS and macOS
Windows
// Remove the `V2TIMSDKListener` event listener. `sdkListener` is the implementation class of `V2TIMSDKListener`.
V2TIMManager.getInstance().removeIMSDKListener(sdkListener);
// Uninitialize the SDK
V2TIMManager.getInstance().unInitSDK();
// `self` is the implementation class of id<V2TIMSDKListener>.
[[V2TIMManager sharedInstance] removeIMSDKListener:self];
// Uninitialize the SDK
[[V2TIMManager sharedInstance] unInitSDK];
// Remove the `V2TIMSDKListener` event listener. `sdkListener` is the instance of V2TIMSDKListener.
V2TIMManager::GetInstance()->RemoveSDKListener(&sdkListener);
// Uninitialize the SDK
V2TIMManager::GetInstance()->UnInitSDK();

FAQs

1. What should I do if error code 6013 is returned along with the description "not initialized" when I call the login or another API?
You must initialize the SDK before using the login, message, group, conversation, relationship chain and profile, and signaling features.