Merge pull request #20 from addhen/shortCutSupport

Add Shortcut support for launching the viewer app on both Android and iOS

Author: eyedol

README.md

@@ -1,4 +1,4 @@
-[![Maven Central](https://img.shields.io/maven-central/v/com.addhen.kanalytics/kanalytics)](https://search.maven.org/search?q=g:com.addhen.kanalytics) ![Build status](https://github.com/addhen/kanalytics/actions/workflows/gradle.yml/badge.svg)
+[![Sonatype Snapshots](https://img.shields.io/nexus/s/com.addhen.kanalytics/kanalytics?server=https%3A%2F%2Foss.sonatype.org)](https://oss.sonatype.org/content/repositories/snapshots/com/addhen/kanalytics/) [![Maven Central](https://img.shields.io/maven-central/v/com.addhen.kanalytics/kanalytics)](https://search.maven.org/search?q=g:com.addhen.kanalytics) ![Build status](https://github.com/addhen/kanalytics/actions/workflows/gradle.yml/badge.svg)
 
 
 # KAnalytics

docs/index.md

@@ -26,6 +26,7 @@ KAnalytics is a flexible analytics library that allows you to:
 2. **Interceptor**: Intercept and modify events before they are sent.
 3. **Multiplatform Support**: Works on both Android and iOS platforms.
 4. **Viewer**: View and debug analytics events during development.
+5. **Shortcuts or Quick Actions**: Allows you to launch KAnalytics Viewer via app shortcuts on Android and Quick action on iOS.
 
 ## Screenshots
 

docs/setup.md

@@ -13,7 +13,7 @@ Add `kanalytics` artifact in your project to be able to collect analytics events
 
 ```kotlin title="build.gradle.kts" linenums="1"
 dependencies {
-  implementation("com.addhen.kanalytics:kanalytics:1.0.0")
+  implementation("com.addhen.kanalytics:kanalytics:x.y.z")
 }
 ```
 
@@ -24,22 +24,22 @@ To view the analytics events, being sent to tracking tools, add the `kanalytics-
 ```kotlin title="build.gradle.kts" linenums="1"
 dependencies {
   if (buildType.name == "debug") {
-    implementation("com.addhen.kanalytics:kanalytics-viewer:1.0.0")
+    implementation("com.addhen.kanalytics:kanalytics-viewer:x.y.z")
   } else {
-    implementation("com.addhen.kanalytics:kanalytics-viewer-no-op:1.0.0")
+    implementation("com.addhen.kanalytics:kanalytics-viewer-no-op:x.y.z")
   }
 
   //On Android, it will simply be
-  debugimplementation("com.addhen.kanalytics:kanalytics-viewer:1.0.0")
-  releaseimplementation("com.addhen.kanalytics:kanalytics-viewer-no-op:1.0.0")
+  debugimplementation("com.addhen.kanalytics:kanalytics-viewer:x.y.z")
+  releaseimplementation("com.addhen.kanalytics:kanalytics-viewer-no-op:x.y.z")
 }
 ```
 
 <details>
 <summary>Snapshots of the development version are available in Sonatype's snapshots repository.</summary>
 <p>
 
-```groovy title="build.gradle.kts" linenums="1"
+```kotlin title="build.gradle.kts" linenums="1"
 repository {
   mavenCentral()
   maven {
@@ -48,13 +48,65 @@ repository {
 }
 
 dependencies {
-  implementation("com.addhen.kanalytics:kanalytics:1.0.0-SNAPSHOT")
+  implementation("com.addhen.kanalytics:kanalytics:x.y.z-SNAPSHOT")
   if (buildType.name == "debug") {
-    implementation("com.addhen.kanalytics:kanalytics-viewer:1.0.0-SNAPSHOT")
+    implementation("com.addhen.kanalytics:kanalytics-viewer:x.y.z-SNAPSHOT")
   } else {
-    implementation("com.addhen.kanalytics:kanalytics-viewer-no-op:1.0.0-SNAPSHOT")
+    implementation("com.addhen.kanalytics:kanalytics-viewer-no-op:x.y.z-SNAPSHOT")
   }
 }
 ```
 </p>
 </details>
+
+
+## Setup Quick Actions on iOS
+
+The quick actions support on iOS requires some manual setup before you can use it.
+
+
+### Install dependency
+
+Export the `kanalytics-viewer` to used in your swift project:
+
+```kotlin title="ios-framework/build.gradle.kts" linenums="1"
+
+kotlin {
+  sourceSets {
+    commonMain {
+      dependencies {
+        // Existing dependencies...
+        // `api` is important here to allow it be exported in the binary framework below
+        api(projects.kanalyticsViewer)
+      }
+    }
+
+    targets.withType<KotlinNativeTarget>().configureEach {
+      binaries.framework {
+        isStatic = true
+        baseName = "KAnalyticsViewerKt"
+        export(projects.kanalyticsViewer)
+      }
+    }
+  }
+}
+```
+
+### Handle Quick Actions in AppDelegate
+Add Quick Actions support by implementing the necessary delegate method in your `AppDelegate` class:
+
+```swift title="AppDelegate.swift" linenums="1"
+import KAnalyticsKt
+
+class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(
+        _ application: UIApplication,
+        configurationForConnecting connectingSceneSession: UISceneSession,
+        options: UIScene.ConnectionOptions
+    ) -> UISceneConfiguration {
+        return KAnalyticsViewerShorcutHandlerKt.getUISceneConfiguration(configurationForConnectingSceneSession: connectingSceneSession)
+    }
+}
+```
+
+For a sample implementation see the sample [iOS app](../sample/ios/iosApp/AppDelegate.swift).

docs/usage.md

@@ -87,6 +87,7 @@ If you're using `KAnalyticsViewer` to view the events to be sent and wants to co
 // Configure event collection
 val collector = KAnalyticsCollector(
   showNotification = true,
+  showShortcut = true,
   duration = RetentionPolicyManager.DayDuration(7)  // Keep events for 7 days
 )
 

gradle/libs.versions.toml

@@ -16,8 +16,16 @@ androidx-core-ktx = "1.15.0"
 androidx-activity-compose = "1.10.0"
 material = "1.12.0"
 appcompat = "1.7.0"
-accompanist-permissions = "0.37.0"
-navigation-compose = "2.8.0-alpha13" # Make use of type-safe compose navigation
+
+# Version 2.8.0-alpha13 causes this issue on iOS builds:
+#
+# Uncaught Kotlin exception: kotlin.native.internal.IrLinkageError: Can not read value from
+# backing field of property 'androidx_compose_runtime_ProvidedValue$stable': Private backing
+# field of property declared in module <org.jetbrains.compose.runtime:runtime> can not be
+# accessed in module <org.jetbrains.compose.material3:material3>
+# Before you bump this version higher than 2.8.0-alpha13 check the iOS app to make
+# it still works.
+navigation-compose = "2.8.0-alpha12" # Make use of type-safe compose navigation
 kotlinx-serializer = "1.8.0"
 lifecycle-viewmodel-compose = "2.8.4"
 kermit = "2.0.5"
@@ -37,7 +45,6 @@ espressoCore = "3.6.1"
 uiautomator = "2.3.0"
 benchmarkMacroJunit4 = "1.3.3"
 profileinstaller = "1.4.1"
-rules = "1.6.1"
 
 [libraries]
 kotlin-test = { module = "org.jetbrains.kotlin:kotlin-test", version.ref = "kotlin" }
@@ -53,7 +60,6 @@ androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref =
 androidx-activity-compose = { module = "androidx.activity:activity-compose", version.ref = "androidx-activity-compose" }
 material = { group = "com.google.android.material", name = "material", version.ref = "material" }
 androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
-accompanist-permissions = { module = "com.google.accompanist:accompanist-permissions", version.ref = "accompanist-permissions" }
 androidx-navigation-compose = { module = "org.jetbrains.androidx.navigation:navigation-compose", version.ref = "navigation-compose" }
 kotlinx-serialization = { group = "org.jetbrains.kotlinx", name = "kotlinx-serialization-json", version.ref = "kotlinx-serializer" }
 lifecycle-viewmodel-compose = { module = "org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "lifecycle-viewmodel-compose" }
@@ -77,7 +83,6 @@ androidx-espresso-core = { group = "androidx.test.espresso", name = "espresso-co
 androidx-uiautomator = { group = "androidx.test.uiautomator", name = "uiautomator", version.ref = "uiautomator" }
 androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "benchmarkMacroJunit4" }
 androidx-profileinstaller = { group = "androidx.profileinstaller", name = "profileinstaller", version.ref = "profileinstaller" }
-androidx-rules = { group = "androidx.test", name = "rules", version.ref = "rules" }
 
 [plugins]
 android-application = { id = "com.android.application", version.ref = "agp" }

gradle/wrapper/gradle-wrapper.jar

@@ -86,8 +86,7 @@ done
 # shellcheck disable=SC2034
 APP_BASE_NAME=${0##*/}
 # Discard cd standard output in case $CDPATH is set (https://github.com/gradle/gradle/issues/25036)
-APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s
-' "$PWD" ) || exit
+APP_HOME=$( cd -P "${APP_HOME:-./}" > /dev/null && printf '%s\n' "$PWD" ) || exit
 
 # Use the maximum available, or set MAX_FD != -1 to use that value.
 MAX_FD=maximum

gradlew

@@ -4,9 +4,13 @@
 package com.addhen.kanalytics.viewer
 
 import android.content.Intent
+import androidx.core.content.pm.ShortcutInfoCompat
+import androidx.core.content.pm.ShortcutManagerCompat
+import androidx.core.graphics.drawable.IconCompat
 import com.addhen.kanalytics.viewer.app.android.ContextInitializer
 import com.addhen.kanalytics.viewer.app.android.MainActivity
 
+private const val SHORTCUT_ID = "kanalytics_viewer_shortcut"
 public actual fun launchViewerApp() {
   val context = ContextInitializer.applicationContext
   context.startActivity(
@@ -18,3 +22,33 @@ public actual fun launchViewerApp() {
 internal actual fun disposeViewerAppWindow() {
   MainActivity.viewerAppMainActivityInstance = null
 }
+
+internal actual fun setupShortcut(shouldCreateShortcut: Boolean) {
+  if (shouldCreateShortcut) {
+    createShortcut()
+  } else {
+    ShortcutManagerCompat.removeDynamicShortcuts(
+      ContextInitializer.applicationContext,
+      listOf(SHORTCUT_ID),
+    )
+  }
+}
+
+private fun createShortcut() {
+  val shortcut = ShortcutInfoCompat.Builder(ContextInitializer.applicationContext, SHORTCUT_ID)
+    .setShortLabel(ContextInitializer.applicationContext.getText(R.string.viewer_app_name))
+    .setLongLabel(ContextInitializer.applicationContext.getText(R.string.shortcut_long_label))
+    .setIcon(
+      IconCompat.createWithResource(ContextInitializer.applicationContext, R.drawable.ic_app_icon),
+    )
+    .setIntent(
+      Intent(ContextInitializer.applicationContext, MainActivity::class.java)
+        .also { intent ->
+          intent.action = Intent.ACTION_VIEW
+          intent.flags = Intent.FLAG_ACTIVITY_NEW_TASK
+        },
+    )
+    .build()
+
+  ShortcutManagerCompat.pushDynamicShortcut(ContextInitializer.applicationContext, shortcut)
+}

kanalytics-viewer/src/androidMain/kotlin/com/addhen/kanalytics/viewer/LaunchViewerApp.android.kt

@@ -3,4 +3,5 @@
   <string name="viewer_app_name">KAnalytics Viewer</string>
   <string name="notification_title">Analytics Event Sent!</string>
   <string name="notification_message">%1$s sent to %2$s</string>
+  <string name="shortcut_long_label">Open KAnalytics Viewer</string>
 </resources>

kanalytics-viewer/src/androidMain/res/values/strings.xml

@@ -16,6 +16,7 @@ import kotlinx.datetime.Instant
 
 public class KAnalyticsCollector(
   private val showNotification: Boolean = true,
+  showShortcut: Boolean = true,
   duration: RetentionPolicyManager.DayDuration = RetentionPolicyManager.DayDuration(7),
 ) {
   private val scope = MainScope()
@@ -28,6 +29,10 @@ public class KAnalyticsCollector(
   private val appCoroutineDispatchers: AppCoroutineDispatchers = AppCoroutineDispatchers()
   private val notificationManager: NotificationManager = NotificationManager()
 
+  init {
+    setupShortcut(showShortcut)
+  }
+
   public fun onEventSent(
     kAnalyticsEvent: KAnalyticsEvent,
     kTrackerName: KTrackerName,

kanalytics-viewer/src/commonMain/kotlin/com/addhen/kanalytics/viewer/KAnalyticsCollector.kt

@@ -6,3 +6,5 @@ package com.addhen.kanalytics.viewer
 public expect fun launchViewerApp()
 
 internal expect fun disposeViewerAppWindow()
+
+internal expect fun setupShortcut(shouldCreateShortcut: Boolean)

kanalytics-viewer/src/commonMain/kotlin/com/addhen/kanalytics/viewer/LaunchViewerApp.kt

@@ -0,0 +1,60 @@
+// Copyright 2025, Addhen Ltd and the kanalytics project contributors
+// SPDX-License-Identifier: Apache-2.0
+
+package com.addhen.kanalytics.viewer
+
+import kotlinx.cinterop.BetaInteropApi
+import platform.UIKit.UIApplicationShortcutItem
+import platform.UIKit.UIScene
+import platform.UIKit.UISceneConfiguration
+import platform.UIKit.UISceneConnectionOptions
+import platform.UIKit.UISceneSession
+import platform.UIKit.UIWindowScene
+import platform.UIKit.UIWindowSceneDelegateProtocol
+import platform.darwin.NSObject
+
+// Credits: https://github.com/BVantur/inspektify/blob/main/inspektify/src/iosMain/kotlin/sp/bvantur/inspektify/ktor/client/InspektifyShortcutHandler.kt
+internal class KAnalyticsViewerSceneDelegate @OverrideInit constructor() :
+  NSObject(),
+  UIWindowSceneDelegateProtocol {
+
+  override fun scene(
+    scene: UIScene,
+    willConnectToSession: UISceneSession,
+    options: UISceneConnectionOptions,
+  ) {
+    onShortcutAction(options.shortcutItem)
+  }
+
+  override fun windowScene(
+    windowScene: UIWindowScene,
+    performActionForShortcutItem: UIApplicationShortcutItem,
+    completionHandler: (Boolean) -> Unit,
+  ) {
+    onShortcutAction(performActionForShortcutItem)
+    launchViewerApp()
+    completionHandler(true)
+  }
+
+  private fun onShortcutAction(shortcutItem: UIApplicationShortcutItem?) {
+    shortcutItem ?: return
+    if (shortcutItem.type != getShortcutType()) return
+
+    launchViewerApp()
+  }
+}
+
+@OptIn(BetaInteropApi::class)
+public fun getUISceneConfiguration(
+  configurationForConnectingSceneSession: UISceneSession,
+): UISceneConfiguration {
+  val configuration = UISceneConfiguration(
+    name = configurationForConnectingSceneSession.configuration.name,
+    sessionRole = configurationForConnectingSceneSession.role,
+  )
+  configuration.delegateClass = KAnalyticsViewerSceneDelegate().`class`()
+  return configuration
+}
+
+@Suppress("FunctionOnlyReturningConstant")
+public fun getShortcutType(): String = SHORTCUT_TYPE

kanalytics-viewer/src/iosMain/kotlin/com/addhen/kanalytics/viewer/KAnalyticsViewerShorcutHandler.kt

@@ -7,12 +7,18 @@ import com.addhen.kanalytics.viewer.app.shared.ui.viewerAppViewController
 import com.addhen.kanalytics.viewer.app.shared.ui.viewerAppViewControllerInstance
 import platform.Foundation.NSProcessInfo
 import platform.UIKit.UIApplication
+import platform.UIKit.UIApplicationShortcutIcon
+import platform.UIKit.UIApplicationShortcutIconType
+import platform.UIKit.UIApplicationShortcutItem
 import platform.UIKit.UIModalPresentationFullScreen
 import platform.UIKit.UINavigationController
 import platform.UIKit.UITabBarController
 import platform.UIKit.UIViewController
 import platform.UIKit.UIWindow
 import platform.UIKit.UIWindowScene
+import platform.UIKit.shortcutItems
+
+public const val SHORTCUT_TYPE: String = "com.addhen.kanalytics.viewer.launch"
 
 public actual fun launchViewerApp() {
   if (viewerAppViewControllerInstance != null) return // Already launched
@@ -62,3 +68,41 @@ private val topWindow: UIWindow?
         .lastOrNull { it.isKeyWindow() }
     }
   }
+
+internal actual fun setupShortcut(shouldCreateShortcut: Boolean) {
+  if (shouldCreateShortcut) {
+    setupShortcut()
+  } else {
+    UIApplication.sharedApplication.shortcutItems = UIApplication.sharedApplication
+      .shortcutItems?.filter {
+        if (it is UIApplicationShortcutItem) {
+          it.type != SHORTCUT_TYPE
+        } else {
+          true
+        }
+      }
+  }
+}
+
+private fun setupShortcut() {
+  if (UIApplication.sharedApplication.shortcutItems?.any {
+      (it as? UIApplicationShortcutItem)?.type == SHORTCUT_TYPE
+    } == true
+  ) {
+    return
+  }
+  val shortcutItem = UIApplicationShortcutItem(
+    type = SHORTCUT_TYPE,
+
+    localizedTitle = "KAnalytics Viewer",
+    localizedSubtitle = "Open KAnalytics Viewer",
+    icon = UIApplicationShortcutIcon.iconWithType(
+      UIApplicationShortcutIconType.UIApplicationShortcutIconTypeCompose,
+    ),
+    userInfo = mapOf<Any?, Any>(),
+  )
+  UIApplication.sharedApplication.shortcutItems =
+    (UIApplication.sharedApplication.shortcutItems?.toMutableList() ?: mutableListOf()).apply {
+      add(shortcutItem)
+    }
+}

kanalytics-viewer/src/iosMain/kotlin/com/addhen/kanalytics/viewer/LaunchViewerApp.ios.kt

@@ -58,7 +58,6 @@ dependencies {
   implementation(libs.androidx.activity.compose)
   implementation(libs.material)
   implementation(libs.androidx.appcompat)
-  implementation(libs.accompanist.permissions)
   implementation(libs.androidx.navigation.compose)
   implementation(libs.androidx.profileinstaller)
 }