Integration Guide

WuKongIM Android SDK integration and initialization configuration guide

Quick Start

Gradle

implementation 'com.github.WuKongIM:WuKongIMAndroidSDK:version' // Please check version number above

For JitPack, you also need to add this to your main project’s build.gradle file:

allprojects {
    repositories {
        ...
        maven { url 'https://jitpack.io' }
    }
}

Since the SDK uses SQLCipher encrypted database and Curve25519 encryption algorithm, you need to add these libraries to your project:

implementation "net.zetetic:android-database-sqlcipher:4.5.3"
implementation "androidx.sqlite:sqlite-ktx:2.3.1"
implementation 'org.whispersystems:curve25519-android:0.5.0'
implementation 'org.whispersystems:signal-protocol-android:2.8.1'

Alternative Installation Methods

Maven

<dependency>
    <groupId>com.github.WuKongIM</groupId>
    <artifactId>WuKongIMAndroidSDK</artifactId>
    <version>version</version>
</dependency>

Manual Integration

1. Download the latest AAR file from GitHub Releases
2. Place the AAR file in your app/libs directory
3. Add to your app/build.gradle:

dependencies {
    implementation files('libs/wukongim-android-sdk-version.aar')
    // Add required dependencies
    implementation "net.zetetic:android-database-sqlcipher:4.5.3"
    implementation "androidx.sqlite:sqlite-ktx:2.3.1"
    implementation 'org.whispersystems:curve25519-android:0.5.0'
    implementation 'org.whispersystems:signal-protocol-android:2.8.1'
}

ProGuard Configuration

Add the following ProGuard rules to your proguard-rules.pro file:

# WuKongIM SDK
-dontwarn com.xinbida.wukongim.**
-keep class com.xinbida.wukongim.**{*;}

# Database encryption
-keep,includedescriptorclasses class net.sqlcipher.** { *; }
-keep,includedescriptorclasses interface net.sqlcipher.** { *; }

# Curve25519 encryption
-keep class org.whispersystems.curve25519.**{*;}
-keep class org.whispersystems.** { *; }
-keep class org.thoughtcrime.securesms.** { *; }

# Additional rules for encryption
-keep class org.signal.** { *; }
-dontwarn org.signal.**

Permissions

Add necessary permissions to your AndroidManifest.xml:

<!-- Network access -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Storage for media files -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

<!-- Microphone for voice messages -->
<uses-permission android:name="android.permission.RECORD_AUDIO" />

<!-- Camera for photo/video messages -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Vibration for notifications -->
<uses-permission android:name="android.permission.VIBRATE" />

<!-- Wake lock for background processing -->
<uses-permission android:name="android.permission.WAKE_LOCK" />

Basic Setup

Initialize in Application

Create or modify your Application class:

// Kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Initialize WuKongIM SDK
        WKIM.getInstance().init(this)
    }
}

// Java
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Initialize WuKongIM SDK
        WKIM.getInstance().init(this);
    }
}

Don’t forget to register your Application class in AndroidManifest.xml:

<application
    android:name=".MyApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme">
    
    <!-- Your activities -->
    
</application>

Configuration Options

You can configure various options during initialization:

// Kotlin
class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Initialize with custom configuration
        val options = WKIMOptions().apply {
            logLevel = WKLogLevel.DEBUG
            dbPassword = "your_db_password"
            fileUploadUrl = "https://your-upload-server.com/upload"
            apiUrl = "https://your-api-server.com"
        }
        
        WKIM.getInstance().init(this, options)
    }
}

// Java
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Initialize with custom configuration
        WKIMOptions options = new WKIMOptions();
        options.setLogLevel(WKLogLevel.DEBUG);
        options.setDbPassword("your_db_password");
        options.setFileUploadUrl("https://your-upload-server.com/upload");
        options.setApiUrl("https://your-api-server.com");
        
        WKIM.getInstance().init(this, options);
    }
}

Verification

To verify that the SDK is properly integrated, add this test code:

// Kotlin
class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        // Test SDK initialization
        val isInitialized = WKIM.getInstance().isInitialized()
        Log.d("WuKongIM", "SDK Initialized: $isInitialized")
        
        // Test connection manager
        val connectionManager = WKIM.getInstance().connectionManager
        Log.d("WuKongIM", "Connection Manager: ${connectionManager != null}")
    }
}

// Java
public class MainActivity extends AppCompatActivity {
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        // Test SDK initialization
        boolean isInitialized = WKIM.getInstance().isInitialized();
        Log.d("WuKongIM", "SDK Initialized: " + isInitialized);
        
        // Test connection manager
        ConnectionManager connectionManager = WKIM.getInstance().getConnectionManager();
        Log.d("WuKongIM", "Connection Manager: " + (connectionManager != null));
    }
}

Troubleshooting

Common Issues

1. Build Error: “Could not resolve dependency”

   • Make sure you’ve added the JitPack repository
   • Check if the version number is correct

2. Runtime Error: “ClassNotFoundException”

   • Verify ProGuard rules are correctly configured
   • Check if all required dependencies are included

3. Database Error: “SQLCipher not found”

   • Ensure SQLCipher dependency is added
   • Check if ProGuard rules for SQLCipher are included

4. Encryption Error: “Curve25519 not found”

   • Verify Curve25519 dependencies are included
   • Check ProGuard rules for encryption libraries

Debug Mode

Enable debug mode to get more detailed logs:

// Kotlin
val options = WKIMOptions().apply {
    logLevel = WKLogLevel.DEBUG
    enableDebugMode = true
}
WKIM.getInstance().init(this, options)

Next Steps

Basic Features

Learn basic SDK functionality usage

Message Handling

Implement message sending and receiving

Channel Management

Manage channels and groups

Conversation Management

Handle conversation lists