feat[live-objects]: add example module showcasing LiveObjects features

Added an Android Compose-based example application demonstrating Ably Live Objects integration. Includes tasks management and color voting screens.

Author: ttypic

build.gradle.kts

@@ -8,6 +8,9 @@ plugins {
     alias(libs.plugins.maven.publish) apply false
     alias(libs.plugins.lombok) apply false
     alias(libs.plugins.test.retry) apply false
+    alias(libs.plugins.android.application) apply false
+    alias(libs.plugins.kotlin.android) apply false
+    alias(libs.plugins.kotlin.compose) apply false
 }
 
 subprojects {

example/.gitignore

@@ -0,0 +1 @@
+/build

example/README.md

@@ -0,0 +1,50 @@
+# Chat Example App
+
+Follow the steps below to get started with chat example app
+
+## Prerequisites
+
+Ensure you have the following installed:
+- [Android Studio](https://developer.android.com/studio) (latest stable version)
+- Java 17 or higher
+- Android SDK with API Level 34 or higher
+
+Add your Ably key to the `local.properties` file:
+
+```properties
+sdk.dir=/path/to/android/sdk
+
+ABLY_KEY=xxxx:yyyyyy
+```
+
+## Steps to Run the App
+
+1. Open in Android Studio
+
+  - Open Android Studio.
+  - Select File > Open and navigate to the cloned repository.
+  - Open the project.
+
+2. Sync Gradle
+
+  - Wait for Gradle to sync automatically.
+  - If it doesn’t, click on Sync Project with Gradle Files in the toolbar.
+
+3. Configure an Emulator or Device
+
+  - Set up an emulator or connect a physical Android device.
+  - Ensure the device is configured with at least Android 5.0 (API 21).
+
+4. Run the App
+
+  - Select your emulator or connected device in the device selector dropdown.
+  - Click on the Run button ▶️ in the toolbar or press Shift + F10.
+
+5. View the App
+
+   Once the build is complete, the app will be installed and launched on the selected device or emulator.
+
+## Troubleshooting
+
+- SDK Not Found: Install missing SDK versions from File > Settings > Appearance & Behavior > System Settings > Android SDK.
+- Build Failures: Check the error logs and resolve dependencies or configuration issues.

example/build.gradle.kts

@@ -0,0 +1,78 @@
+import java.io.FileInputStream
+import java.io.InputStreamReader
+import java.util.Properties
+
+plugins {
+    alias(libs.plugins.android.application)
+    alias(libs.plugins.kotlin.android)
+    alias(libs.plugins.kotlin.compose)
+}
+
+android {
+    namespace = "com.ably.example"
+    compileSdk = 35
+
+    defaultConfig {
+        applicationId = "com.ably.example"
+        minSdk = 30
+        targetSdk = 35
+        versionCode = 1
+        versionName = "1.0"
+
+        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
+
+        buildConfigField("String", "ABLY_KEY", "\"${getLocalProperty("ABLY_KEY") ?: ""}\"")
+    }
+
+    buildTypes {
+        release {
+            isMinifyEnabled = false
+            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"), "proguard-rules.pro")
+        }
+    }
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_11
+        targetCompatibility = JavaVersion.VERSION_11
+    }
+    kotlinOptions {
+        jvmTarget = "11"
+    }
+    buildFeatures {
+        compose = true
+        buildConfig = true
+    }
+}
+
+dependencies {
+    implementation(libs.core.ktx)
+    implementation(libs.lifecycle.runtime.ktx)
+    implementation(libs.activity.compose)
+    implementation(platform(libs.compose.bom))
+    implementation(libs.ui)
+    implementation(libs.ui.graphics)
+    implementation(libs.ui.tooling.preview)
+    implementation(libs.material3)
+
+    implementation(project(":live-objects"))
+    implementation(project(":android"))
+
+    implementation(libs.navigation.compose)
+
+    testImplementation(libs.junit)
+    androidTestImplementation(libs.ext.junit)
+    androidTestImplementation(libs.espresso.core)
+    androidTestImplementation(platform(libs.compose.bom))
+    androidTestImplementation(libs.ui.test.junit4)
+    debugImplementation(libs.ui.tooling)
+    debugImplementation(libs.ui.test.manifest)
+}
+
+fun getLocalProperty(key: String, file: String = "local.properties"): String? {
+    val properties = Properties()
+    val localProperties = File(file)
+    if (!localProperties.isFile) return null
+    InputStreamReader(FileInputStream(localProperties), Charsets.UTF_8).use { reader ->
+        properties.load(reader)
+    }
+    return properties.getProperty(key)
+}

example/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

example/src/main/AndroidManifest.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+
+    <application
+            android:allowBackup="true"
+            android:icon="@mipmap/ic_launcher"
+            android:label="@string/app_name"
+            android:roundIcon="@mipmap/ic_launcher_round"
+            android:supportsRtl="true"
+            android:theme="@style/Theme.Ably">
+        <activity
+                android:name=".MainActivity"
+                android:exported="true"
+                android:label="@string/app_name"
+                android:theme="@style/Theme.Ably">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN"/>
+
+                <category android:name="android.intent.category.LAUNCHER"/>
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>

example/src/main/java/com/ably/example/MainActivity.kt

@@ -0,0 +1,53 @@
+package com.ably.example
+
+import android.os.Bundle
+import androidx.activity.ComponentActivity
+import androidx.activity.compose.setContent
+import androidx.activity.enableEdgeToEdge
+import com.ably.example.screen.MainScreen
+import com.ably.example.ui.theme.AblyTheme
+import io.ably.lib.realtime.AblyRealtime
+import io.ably.lib.types.ClientOptions
+import io.ably.lib.util.Log
+
+class MainActivity : ComponentActivity() {
+  private val realtimeClient: AblyRealtime by lazy {
+    AblyRealtime(
+      ClientOptions().apply {
+        key = BuildConfig.ABLY_KEY
+        logLevel = Log.VERBOSE
+        autoConnect = false
+      }
+    )
+  }
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    enableEdgeToEdge()
+    setContent {
+      AblyTheme {
+        MainScreen(realtimeClient)
+      }
+    }
+  }
+
+  override fun onStart() {
+    super.onStart()
+    realtimeClient.connect()
+  }
+
+  override fun onStop() {
+    super.onStop()
+    realtimeClient.close()
+  }
+
+  override fun onResume() {
+    super.onResume()
+    realtimeClient.connect()
+  }
+
+  override fun onPause() {
+    super.onPause()
+    realtimeClient.close()
+  }
+}