Traceless analytics sdk
Skill maichanchinh/claude-skills/skills/traceless-analytics-sdk
Traceless Analytics SDK for Android - Firebase-first analytics SDK for tracking screen views and UI interactions. Use when implementing, modifying, or extending Android analytics tracking with this SDK: (1) Screen view tracking with Analytics.enterScreen(), (2) UI interaction tracking with Analytics.trackUI(), (3) Jetpack Compose integration, (4) Debugging analytics issues, (5) Writing tests for analytics functionality. Supports custom screens/actions, session-aware context management, and Compose helpers.From its SKILL.md
npx -y skills add maichanchinh/claude-skills --skill traceless-analytics-sdkAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
9.8 KB, as published. Nobody here has run it
Traceless Analytics SDK
Overview
Firebase-first Android analytics SDK for tracking screen views and UI interactions with session-aware context management.
Installation
dependencies {
implementation("io.github.maichanchinh:traceless-analytic:2.0.+")
}
Package Imports
// Core SDK
import com.app.traceless.analytic.Analytics
import com.app.traceless.analytic.UIAction
import com.app.traceless.analytic.UIScreen
import com.app.traceless.analytic.TracelessEvent
// Coroutines (for collecting events)
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.collectLatest
import kotlinx.coroutines.launch
Screen Management
Define all app screens in one place using a sealed class:
// screens/AppScreens.kt - Centralized screen definitions
sealed class AppScreens : UIScreen() {
data object Splash : AppScreens("splash")
data object Home : AppScreens("home")
data object ProductDetail : AppScreens("product_detail")
data object Settings : AppScreens("settings")
data object Profile : AppScreens("profile")
}
// Usage
Analytics.enterScreen(AppScreens.Home)
Analytics.enterScreen(AppScreens.ProductDetail)
Benefits:
- Single source of truth for all screens
- Compile-time safety (exhaustive when branching)
- Easy to refactor screen names
- Prevents typos and duplicate definitions
Quick Start
// Imports
import com.app.traceless.analytic.Analytics
import com.app.traceless.analytic.UIAction
import com.app.traceless.analytic.UIScreen
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.collectLatest
import kotlinx.coroutines.launch
// Setup in Application.onCreate()
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
if (BuildConfig.DEBUG) Analytics.enableDebug()
Analytics.initialize()
// Collect events and dispatch to Firebase
CoroutineScope(Dispatchers.Main).launch {
Analytics.listenEvents().collectLatest { event ->
Firebase.analytics.logEvent(event.name) {
event.params.forEach { (key, value) ->
when (value) {
is String -> param(key, value)
is Long -> param(key, value)
is Double -> param(key, value)
}
}
}
}
}
}
}
// Track screen views
Analytics.enterScreen(AppScreens.Splash)
Analytics.enterScreen(AppScreens.Home)
// Track UI interactions
Analytics.trackUI("btn_buy", UIAction.Click)
Analytics.trackUI("input_email", UIAction.Input)
// With custom parameters
Analytics.enterScreen(AppScreens.Home, mapOf("source" to "notification"))
Analytics.trackUI("btn_buy", UIAction.Click, mapOf("value" to 99.99))
Core API
Analytics (public API)
├── initialize() → Initialize SDK
├── enableDebug() / disableDebug() → Debug mode
├── enterScreen(screen: AppScreens, customParams?) → screen_view event
├── trackUI(elementId: String, action: UIAction, customParams?) → ui_interaction event
├── listenEvents() → SharedFlow<TracelessEvent> for Firebase integration
└── resetState() → Reset on new session
Key: Use listenEvents() to collect events and dispatch to Firebase Analytics.
Custom Parameters
Both enterScreen() and trackUI() accept optional custom parameters:
// Screen view with custom params
Analytics.enterScreen(
screen = AppScreens.Home,
customParams = mapOf(
"source" to "deeplink",
"campaign" to "summer2024"
)
)
// UI interaction with custom params
Analytics.trackUI(
elementId = "btn_buy",
action = UIAction.Click,
customParams = mapOf(
"value" to 99.99,
"currency" to "USD",
"item_id" to "prod_123"
)
)
Note: Custom params merge with default params. Overlapping keys will override defaults.
Parameter Key Convention
Custom parameter keys must follow snake_case convention:
- ✅ Valid:
user_id,total_amount,item_price,campaign_id - ✅ camelCase auto-converted:
userId→user_id,totalAmount→total_amount - ❌ Invalid:
USER-ID,total-amount,userId!,TOTAL_AMOUNT
// snake_case - used as-is
Analytics.trackUI("btn_buy", UIAction.Click, mapOf(
"user_id" to "12345",
"total_amount" to 99.99
))
// camelCase - auto-converted to snake_case (logs warning in debug mode)
Analytics.trackUI("btn_buy", UIAction.Click, mapOf(
"userId" to "12345", // → user_id
"totalAmount" to 99.99 // → total_amount
))
// Invalid - throws IllegalArgumentException
Analytics.trackUI("btn_buy", UIAction.Click, mapOf(
"USER-ID" to "12345" // ❌ throws error
))
Reserved Keys (avoid overriding):
screen_nameelement_idactionis_manual
Screen Naming Rules
- Use snake_case format
- Max 50 characters
- Lowercase letters and underscores only
- Business identifiers only (e.g., "home", "product_detail")
Predefined UI Actions
Click, Input, Submit, Toggle, Swipe, Navigate,
View, Refresh, Dismiss, Select
Custom actions: object LongPress : UIAction("long_press")
Firebase Integration
Traceless SDK emits events via SharedFlow that you collect and dispatch to Firebase Analytics:
import android.app.Application
import com.app.traceless.analytic.Analytics
import com.app.traceless.analytic.TracelessEvent
import com.google.firebase.Firebase
import com.google.firebase.analytics.FirebaseAnalytics
import com.google.firebase.analytics.analytics
import com.google.firebase.analytics.logEvent
import com.google.firebase.analytics.param
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.flow.collectLatest
import kotlinx.coroutines.launch
import timber.log.Timber
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
// 1. Initialize SDK
Analytics.enableDebug()
Analytics.initialize()
// 2. Collect events and dispatch to Firebase
CoroutineScope(Dispatchers.Main).launch {
Analytics.listenEvents().collectLatest { event ->
// Debug logging
Timber.tag("Analytics").d(
"[Event] ${event.name} | " +
"screen: ${event.screenName} | " +
"element: ${event.elementId} | " +
"action: ${event.action} | " +
"params: ${event.params}"
)
// 3. Dispatch to Firebase Analytics
dispatchToFirebase(event)
}
}
}
private fun dispatchToFirebase(event: TracelessEvent) {
val firebaseAnalytics = Firebase.analytics
firebaseAnalytics.logEvent(event.name) {
event.params.forEach { (key, value) ->
when (value) {
is String -> param(key, value)
is Long -> param(key, value)
is Double -> param(key, value)
is Boolean -> param(key, value)
}
}
}
}
}
Event Structure
Each TracelessEvent contains:
name: String- Event name ("screen_view", "ui_interaction")params: Map<String, Any>- Event parameterstimestamp: Long- Unix timestamp- Extension properties:
screenName: String?- Current screen nameelementId: String?- UI element identifieraction: String?- UI action performedisManual: Boolean- Whether event is manually tracked
Flow Behavior
- Uses
SharedFlowwithreplay=0- new collectors don't receive past events - Buffer capacity: 64 events with
DROP_OLDESTstrategy - Collected on
Dispatchers.Mainfor safe Firebase calls
Jetpack Compose Integration
// Recommended: TrackScreen helper
@Composable
fun ProductDetailScreen() {
TrackScreen(AppScreens.ProductDetail) // Auto track once
Button(onClick = {
Analytics.trackUI("btn_buy", UIAction.Click)
}) {
Text("Buy")
}
}
// Manual: LaunchedEffect pattern
@Composable
fun MyScreen() {
LaunchedEffect(Unit) {
Analytics.enterScreen(AppScreens.Home)
}
}
Session Management
| Scenario | Handling |
|---|---|
| App background | Don't reset screen state |
| New session | Reset currentScreenName |
| Offline | Queue events (best-effort) |
| Crash | Don't retry events |
// Reset on new Firebase session
fun onNewFirebaseSession() {
Analytics.resetState()
}
Key Principles
- Minimal State: Keep internal state minimal (currentScreenName, sessionId)
- Session-Aware: Events include session context automatically
- Graceful Degradation: Handle Firebase failures without crashing
- Best-Effort Offline: Queue events when offline, don't block
- Single Responsibility: Each function does one thing well
Common Pitfalls
Don't track screen in onClick - Use LaunchedEffect(Unit) or TrackScreen helper instead.
Avoid duplicate tracking - Track screen only once per screen lifecycle, not in both onCreate and onResume.
Handle configuration changes - Use savedInstanceState check to avoid re-tracking on rotation.