Chatist Android SDK Example App

This is a comprehensive example Android application demonstrating the integration and usage of the Chatist Android SDK. The app showcases how to properly implement the SDK in your Android project, including customer management, push notifications via Firebase Cloud Messaging (FCM), and the complete chat UI.

📱 Features

• Complete Chatist SDK Integration: Full implementation of customer support chat functionality
• Customer Session Management: Login/logout functionality with session persistence
• Push Notifications: Firebase Cloud Messaging integration for real-time message notifications
• In-App Notifications: Beautiful notification overlay for incoming messages
• Unread Message Tracking: Real-time count of unread support messages
• Intent Handling: Deep linking support for notification tap actions
• Analytics Support: Optional analytics event provider integration

🛠️ Requirements

• Android Studio (latest version recommended)
• Minimum SDK: API 24 (Android 7.0)
• Target SDK: API 36
• Kotlin 2.2.20
• Java 17
• Chatist SDK: 1.0.0

🔧 Setup

1. SDK Dependency

The Chatist Android SDK is available on Maven Central. Add the dependency to your app/build.gradle.kts:

dependencies {
    implementation("com.chatist:chatist-sdk-android:1.0.0")
}

Or if using a version catalog (gradle/libs.versions.toml):

[versions]
chatist = "1.0.0"

[libraries]
chatist = { module = "com.chatist:chatist-sdk-android", version.ref = "chatist"}

2. API Key Configuration

Update the API key in ExampleApp.kt:

ChatistSdk.init(
    context = this,
    enableLogging = true,
    environment = Environment.Alpha,  // or Environment.Production for production
    apiKey = "Your API Key",  // Replace with your actual API key
    appVersion = "1.0.0",
    appVersionCode = 1,
    analyticsEventProvider = null,  // Optional: Your analytics provider
)

3. Firebase Configuration

Add your google-services.json file to the app/ directory. This file is required for Firebase Cloud Messaging to work properly. Don't forget to generate a private key from the Firebase Console and set it on the Chatist Admin page. More info: https://fcmtest.com/generate-private-key

🚀 Core Implementation

SDK Initialization and Login

The SDK initialization and customer login happen in the ExampleApp class (app/src/main/java/com/chatist/sdk/example/ExampleApp.kt):

class ExampleApp : Application() {
    override fun onCreate() {
        super.onCreate()
        
        // Initialize the SDK
        ChatistSdk.init(
            context = this,
            enableLogging = BuildConfig.DEBUG,
            environment = Environment.Production,
            apiKey = "Your API Key",
            appVersion = BuildConfig.VERSION_NAME,
            appVersionCode = BuildConfig.VERSION_CODE,
            analyticsEventProvider = null  // Optional
        )
        
        // Login the customer to enable notifications
        ChatistSdk.login()
    }
}

Important: The login() call is essential for:

• Enabling push notifications for support messages
• Establishing customer session with the backend
• Associating the device with the customer
• Accessing conversation history

Main Activity Implementation

The MainActivity.kt demonstrates the complete UI integration with animations and unread message tracking:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        enableEdgeToEdge()
        
        // Handle notification intents (deep links)
        val intentAction = ChatistSdk.notificationManager.handleIntent(this.intent)
        
        setContent {
            var isChatistVisible by rememberSaveable { mutableStateOf(false) }
            
            // Handle back navigation
            BackHandler(isChatistVisible) {
                isChatistVisible = false
            }
            
            // Animated Chat UI with slide transitions
            AnimatedVisibility(
                visible = isChatistVisible,
                enter = slideInVertically(initialOffsetY = { it }),
                exit = slideOutVertically(targetOffsetY = { it }),
            ) {
                ChatistSdk.ChatistUi(
                    modifier = Modifier.fillMaxSize(),
                    intentAction = intentAction,
                    onClose = { isChatistVisible = false }
                )
            }
            
            // Track unread messages
            val unreadCount = ChatistSdk.notificationManager.unreadMessageCount
                .collectAsStateWithLifecycle()
            
            // Main screen content
            AnimatedVisibility(
                visible = !isChatistVisible,
                enter = fadeIn(),
                exit = fadeOut()
            ) {
                Column(
                    modifier = Modifier.fillMaxSize(),
                    verticalArrangement = Arrangement.Center,
                    horizontalAlignment = Alignment.CenterHorizontally,
                ) {
                    Button(onClick = { isChatistVisible = true }) {
                        Text("Open Chatist")
                    }
                    Spacer(modifier = Modifier.height(32.dp))
                    Text("Unread messages: ${unreadCount.value}")
                }
            }
        }
    }
}

🔥 Firebase Integration

ExampleFirebaseMessagingService

The Firebase Cloud Messaging service (app/src/main/java/com/chatist/sdk/example/ExampleFirebaseMessagingService.kt) handles push notifications:

class ExampleFirebaseMessagingService : FirebaseMessagingService() {

    override fun onNewToken(token: String) {
        super.onNewToken(token)
        // Forward the FCM token to Chatist SDK
        ChatistSdk.notificationManager.setDeviceToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        super.onMessageReceived(message)
        // Let Chatist SDK handle the message
        ChatistSdk.notificationManager.onMessageReceived(message)
    }
}

The service is registered in AndroidManifest.xml:

<service
    android:name=".example.ExampleFirebaseMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

📊 Customer Management

Update customer information after authentication:

// After user login in your app
ChatistSdk.customerManager.updateCustomerInfo(
    originalId = user.id,        // Your system's user ID
    email = user.email           // Customer email address
)

This associates support conversations with specific users and enables personalized support.

🔔 In-App Notifications

Display beautiful in-app notification overlays when messages arrive while the app is active:

@Composable
fun MyScreen() {
    val notificationState = rememberNotificationState()
    
    Box(modifier = Modifier.fillMaxSize()) {
        // Main content
        MyContent()
        
        // In-app notification overlay
        notificationState.message?.let { message ->
            ChatistSdk.ChatistInAppNotification(
                modifier = Modifier
                    .align(Alignment.TopCenter)
                    .padding(16.dp)
                    .fillMaxWidth(),
                message = message,
                onClose = { notificationState.dismiss() }
            )
        }
    }
}

Features:

• Auto-dismisses after 3 seconds
• Smooth fade animations
• Themed according to Chatist branding
• Shows sender avatar and message
• Manual dismiss option

🔄 Session Lifecycle Management

Login Flow

// In your app's login flow
private fun onUserLoginSuccess(user: User) {
    // Login to Chatist SDK
    ChatistSdk.login()
    
    // Update customer information
    ChatistSdk.customerManager.updateCustomerInfo(
        originalId = user.id,
        email = user.email
    )
    
    // SDK is ready for use
    navigateToMainScreen()
}

Logout Flow

// In your app's logout flow
private fun onUserLogout() {
    // Logout from Chatist SDK (stops notifications)
    ChatistSdk.logout()
    
    // Clear your app's user session
    clearUserSession()
    navigateToLoginScreen()
}

User Switching

private fun switchUser(newUser: User) {
    // Logout current user
    ChatistSdk.logout()
    
    // Login new user
    ChatistSdk.login()
    ChatistSdk.customerManager.updateCustomerInfo(
        originalId = newUser.id,
        email = newUser.email
    )
}

📂 Project Structure

chatist-android-sdk/
├── app/                          # Example application module
│   ├── src/
│   │   └── main/
│   │       ├── java/
│   │       │   └── com/chatist/sdk/example/
│   │       │       ├── ExampleApp.kt                      # Application class with SDK init
│   │       │       ├── ExampleFirebaseMessagingService.kt # FCM service implementation
│   │       │       ├── MainActivity.kt                    # Main activity with chat UI
│   │       │       └── theme/                            # App theming
│   │       │           ├── Theme.kt
│   │       │           └── Type.kt
│   │       └── AndroidManifest.xml
│   └── build.gradle.kts
├── gradle/
│   └── libs.versions.toml       # Version catalog for dependencies
├── settings.gradle.kts           # Project settings with GitHub Packages config
└── build.gradle.kts             # Root build configuration

🚀 Getting Started

1. Clone the repository
2. Add your google-services.json file to the app/ directory
3. Replace the API key in ExampleApp.kt with your actual Chatist API key
4. Build and run the app

💡 Advanced Features

Analytics Integration

Integrate your analytics provider to track SDK events:

class MyAnalyticsProvider : AnalyticsEventProvider {
    override fun trackEvent(eventName: String, parameters: Map<String, Any>) {
        // Forward to your analytics service
        Analytics.track(eventName, parameters)
    }
}

// During SDK initialization
ChatistSdk.init(
    // ... other parameters
    analyticsEventProvider = MyAnalyticsProvider()
)

Handling Notification Intents

The SDK can handle deep links from notification taps:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    
    // Handle notification tap intent
    val intentAction = ChatistSdk.notificationManager.handleIntent(intent)
    
    // Pass to ChatistUi
    ChatistSdk.ChatistUi(
        intentAction = intentAction,
        // ... other parameters
    )
}

Unread Message Tracking

Monitor unread message count in real-time:

@Composable
fun UnreadBadge() {
    val unreadCount by ChatistSdk.notificationManager
        .unreadMessageCount
        .collectAsStateWithLifecycle()
    
    if (unreadCount > 0) {
        Badge(count = unreadCount)
    }
}

📝 Important Notes

• SDK Initialization: Must be called before using any SDK features, preferably in Application.onCreate()
• Customer Login: Required before opening the chat UI to enable notifications and session management
• Thread Safety: All SDK methods are thread-safe
• ProGuard/R8: The SDK includes consumer ProGuard rules; no additional configuration needed
• Documentation: Every public class in the SDK is well documented and ships with the AAR
• Firebase: Ensure google-services.json is properly configured for your app

🔐 Security Considerations

• Store API keys securely; consider using build configurations for different environments
• Use ProGuard/R8 in production builds for code obfuscation
• Implement proper user authentication before calling ChatistSdk.login()
• Clear customer data on logout using ChatistSdk.logout()

📚 SDK Documentation

The Chatist SDK provides comprehensive JavaDoc/KDoc documentation for all public APIs. Key components include:

• ChatistSdk: Main entry point for SDK initialization and UI access
• NotificationManager: Handles push notifications and device tokens
• CustomerManager: Manages customer information and sessions
• ChatistUi: Composable function for the chat interface
• ChatistInAppNotification: Composable for in-app message overlays

🆘 Support

For issues or questions about the Chatist SDK, please contact your Chatist support representative or refer to the SDK documentation shipped with the AAR.

📄 License

This example app is provided as-is for demonstration purposes. The Chatist SDK is subject to its own license agreement.