diff --git a/README.md b/README.md index 2250581c..770dc728 100644 --- a/README.md +++ b/README.md @@ -6,42 +6,11 @@ Inspired from [Flipper](https://github.com/facebook/flipper) by Meta, while leve It allows developers to connect a Kotlin Multiplatform or Android app to their computer and launch a **desktop interface** that can **observe, inspect, and interact with the running app** in real time — across shared Kotlin code and platform-specific implementations. -**Works on** -| | Android | Desktop (jvm) | iOS (simulator) | iOS (device) | wasm | -|---|:---:|:---:|:---:|:---:|:---:| -| Network | ✅ | ✅ | ✅ | ❌ | ❌ | -| Database | ✅ | ✅ | ✅ | ❌ | ❌ | -| Preference | ✅ | ❌ | ❌ | ❌ | ❌ | -| Table | ✅ | ✅ | ✅ | ❌ | ❌ | -| Analytics | ✅ | ✅ | ✅ | ❌ | ❌ | -| Deeplink | ✅ | ❌ | ❌ | ❌ | ❌ | -| Files | ✅ | ❌ | ❌ | ❌ | ❌ | -| Images | ✅ | ✅ | ✅ | ❌ | ❌ | -| Dashboards | ✅ | ✅ | ✅ | ❌ | ❌ | - -With Flocon, you gain deep access to critical app internals — such as -- network requests (HTTP, gRPC, GraphQL, WebSockets) -- mock network calls -- local storage (sharedpref, databases, app files) -- analytics events (and custom events) -- debug menu displayed on the desktop -- deeplinks - -and more — without needing root access or tedious ADB commands. - -It’s designed for modern multiplatform development, accelerating debugging, QA, and iteration cycles. +--- Screenshot 2025-09-12 at 15 39 45 ---- - -## 🚀 What Can Flocon Do? - -Once your device (Android / iOS / Desktop) is connected and your app includes the Flocon SDK, you can use the desktop companion app to access the following features: - ---- - -🛠️ Getting Started +## Getting Started `This library is lightweight, contributing just 140KB to the overall app size` @@ -70,642 +39,67 @@ flocon = "LASTEST_VERSION" flocon = { module = "io.github.openflocon:flocon", version.ref = "flocon" } ``` -Download & install the last `Desktop client` +## 📖 Documentation -https://github.com/openflocon/Flocon/releases +Visit the full documentation site for setup guides, feature details, and advanced usage: +👉 **[openflocon.github.io/Flocon/](https://openflocon.github.io/Flocon/)** -### 📡 Network Request Inspector (kotlin multi platform compatible) +### Table of Contents -Screenshot 2025-09-12 at 15 39 55 - -Screenshot 2025-09-12 at 15 40 03 - -Flocon captures **all outgoing network requests** made by the Android app — whether they’re simple REST API calls or complex multipart uploads — and displays them in an organized UI. - -For each request, you can inspect: - -- HTTP method (GET, POST, etc.) -- Full URL -- Request headers and body -- Response headers and body -- Status code and response time -- Timestamp - -This feature is invaluable for diagnosing backend issues, debugging unexpected API failures, and verifying request payloads and authentication headers. - -#### 🎭 HTTP Request Mocking (kotlin multi platform compatible) - -Screenshot 2025-09-12 at 15 40 38 - -Beyond simple inspection, Flocon now allows you to mock HTTP requests. This powerful feature gives you full control over your app's network layer without needing to change any code. You can intercept specific network calls and provide custom responses, making it easy to test various scenarios. - -With this feature, you can: - -- Simulate network errors: Test how your app handles different HTTP status codes (e.g., 404 Not Found, 500 Server Error). -- Create test data: Mock responses with specific data to test different UI states, even if your backend isn't ready yet. -- Create a new mock from an existing request, then test your app with some differences inside the prefious body -- Reduce dependencies: Develop and test features without needing a stable internet connection or a complete backend environment. - -#### With OkHttp (android only) - -[![Maven Central](https://img.shields.io/maven-central/v/io.github.openflocon/flocon-okhttp-interceptor.svg)](https://search.maven.org/artifact/io.github.openflocon/flocon-okhttp-interceptor) - -``` -debugImplementation("io.github.openflocon:flocon-okhttp-interceptor:LAST_VERSION") -releaseImplementation("io.github.openflocon:flocon-okhttp-interceptor-no-op:LAST_VERSION") -``` - -```kotlin -val okHttpClient = OkHttpClient() - .newBuilder() - .addInterceptor(FloconOkhttpInterceptor()) - .build() -``` - -#### With Ktor (kotlin multi platform compatible) - -[![Maven Central](https://img.shields.io/maven-central/v/io.github.openflocon/flocon-ktor-interceptor.svg)](https://search.maven.org/artifact/io.github.openflocon/flocon-ktor-interceptor) - -tested with ktor `3.2.3` - -``` -debugImplementation("io.github.openflocon:flocon-ktor-interceptor:LAST_VERSION") -releaseImplementation("io.github.openflocon:flocon-ktor-interceptor-no-op:LAST_VERSION") -``` - -```kotlin -val httpClient = HttpClient(YourClient) { - install(FloconKtorPlugin) - ... -} -``` - -### 💬 Inspect Websockets - -Screenshot 2025-10-04 at 23 44 57 - -Flocon doesn’t stop at HTTP — it also captures **all WebSocket communications** made by your Android app. -This allows you to inspect real-time data exchanges between your app and the server with full visibility. - -For each WebSocket connection, you can inspect: - -- Connection URL -- **Sent and received frames** (text, binary, ping/pong) -- **Timestamps** and message order -- **Payloads** -- **Closes** - -With this feature, you can: - -- Debug real-time features like chat, live feeds, or multiplayer updates -- Verify the exact content of messages exchanged -- Diagnose disconnection or synchronization issues - -#### With OkHttp3 (android only) - -Flocon-Okhttp-Interceptor has built-in websocket methods (⚠️ it's not possible through interceptors ⚠️) - -To log outgoing messages -```kotlin -webSocket.sendWithFlocon("\"$text\"") // extension method that log to Flocon and performs the send -``` - -To log incoming messages -```kotlin -val request = Request.Builder() - .url("wss://.......") - .build() -val listener = object : WebSocketListener() { - // your listener -} - -webSocket = client.newWebSocket( - request, - listener.listenWithFlocon(id = "wss://......."), // extension method that wraps an existing WebSocketListener - ) -} -``` - -#### 🧰 Manually (kotlin multi platform compatible) - -If you are using other websockets libs than okhttp, you can easily forward events to FloconWebSocket - -To log outgoing messages -```kotlin -val message = "hello" - -webSocket.send(message) - -floconLogWebSocketEvent( - FloconWebSocketEvent( - websocketUrl = "ws://...", - event = FloconWebSocketEvent.Event.SendMessage, - message = message, - ) -) -``` - -To log incoming messages -```kotlin -myCustomWebSocket.onReceived { - floconLogWebSocketEvent( - FloconWebSocketEvent( - websocketUrl = "ws://..." - event = FloconWebSocketEvent.Event.ReceiveMessage, - message = it, - ) - // handle your message -) -``` - -### 🛰️ GraphQL Request Inspector - -Flocon also supports **GraphQL** requests via a dedicated Apollo interceptor. - -Just like with REST, all outgoing GraphQL requests made through [Apollo Client](https://www.apollographql.com/docs/android/) are captured and displayed in Flocon’s interface — allowing you to debug your queries and mutations in real time. - - -For each GraphQL call, you can inspect: - -- Response data or error payload -- Headers, status code, and response time -- The operation type (query / mutation) - -```kotlin -ApolloClient.Builder() - // just set your already configured with flocon okhttp interceptor client - .okHttpClient(client) - // regular builder methods - .build() -``` - -### 🖼️ Downloaded Image Viewer - -Screenshot 2025-09-12 at 15 40 53 - -Flocon captures and displays **images downloaded by the Android app**, giving you a clear, visual representation of media fetched over the network — such as avatars, product thumbnails, banners, or any other images requested at runtime. - -For each image, Flocon shows: - -- A live **thumbnail preview** of the image -- The **URL** from which it was downloaded -- The **download timestamp** - -This feature is extremely useful for: - -- Verifying that images are loading correctly and not broken -- Debugging CDN issues, placeholders, or misconfigured URLs -- Comparing image quality and compression at runtime -- Inspecting lazy loading or image caching behaviors - -Whether you're working on UI/UX, performance optimization, or just debugging a missing image, this tool gives you **immediate visibility** into every image fetched by your app. - -Usage with coil - -```kotlin -// just add your okhttp client (with the flocon interceptor) -SingletonImageLoader.setSafe { - ImageLoader.Builder(context = context) - .components { - // works also for ktor network fetcher - add( - coil3.network.okhttp.OkHttpNetworkFetcherFactory( - callFactory = { - okHttpClient - }, - ), - ) - } - .build() -} -``` +- 🚀 **[Getting Started](https://openflocon.github.io/Flocon/setup)** + - [Installation Guide](https://openflocon.github.io/Flocon/setup#installation) + - [Basic Usage](https://openflocon.github.io/Flocon/setup#usage) + - [macOS Specifics](https://openflocon.github.io/Flocon/macos-install) +- 📡 **[Networking](https://openflocon.github.io/Flocon/network)** + - [HTTP Inspector](https://openflocon.github.io/Flocon/network#📡-network-request-inspector) + - [Request Mocking](https://openflocon.github.io/Flocon/network#🎭-http-request-mocking) + - [GraphQL](https://openflocon.github.io/Flocon/graphql) + - [gRPC](https://openflocon.github.io/Flocon/grpc) + - [WebSockets](https://openflocon.github.io/Flocon/websocket) +- 💾 **[Local Storage](https://openflocon.github.io/Flocon/database)** + - [Database Explorer (Room & SQLite)](https://openflocon.github.io/Flocon/database) + - [Shared Preferences (Android)](https://openflocon.github.io/Flocon/sharedpref) +- 🛠️ **[Advanced Debugging](https://openflocon.github.io/Flocon/dashboard)** + - [Custom Dashboards](https://openflocon.github.io/Flocon/dashboard) + - [Dynamic Data Tables](https://openflocon.github.io/Flocon/table) + - [Deeplink Launcher](https://openflocon.github.io/Flocon/deeplink) + - [File Explorer](https://openflocon.github.io/Flocon/files) + - [Analytics Viewer](https://openflocon.github.io/Flocon/analytics) + - [Image Previewer](https://openflocon.github.io/Flocon/image) +- ❓ **[Troubleshooting](https://openflocon.github.io/Flocon/troubleshooting)** --- -### 📊 Analytics Event Viewer +## ✨ Features at a Glance -Screenshot 2025-09-12 at 15 41 27 - -Screenshot 2025-09-12 at 15 41 32 - -Flocon shows a real-time stream of **analytics events** emitted by your application. Whether you’re using Firebase Analytics, Segment, or a custom solution, the Flocon SDK can be plugged and forward these events to the desktop UI. - -Each event includes: - -- The event name -- Parameters and metadata -- Timestamps - -This is especially useful for QA teams and product analysts to validate that the right events are triggered at the right time, with the correct payloads. - -```kotlin -floconAnalytics("firebase").logEvents( - AnalyticsEvent( - eventName = "clicked user", - "userId" analyticsProperty "1024", - "username" analyticsProperty "florent", - "index" analyticsProperty "3", - ), - AnalyticsEvent( - eventName = "opened profile", - "userId" analyticsProperty "2048", - "username" analyticsProperty "kevin", - "age" analyticsProperty "34", - ), -``` +| Feature | Android | KMP (JVM/iOS) | +|---|:---:|:---:| +| **Network (HTTP/Mocking)** | ✅ | ✅ | +| **Database (Room/SQLite)** | ✅ | ✅ | +| **Preferences** | ✅ | ❌ | +| **Dashboards & Tables** | ✅ | ✅ | +| **Analytics & Images** | ✅ | ✅ | +| **Deeplink & Files** | ✅ | ❌ | --- -### 🗝 SharedPreferences Explorer & Editor (android only) - -Screenshot 2025-09-12 at 15 41 04 - -Flocon provides complete access to your app’s **SharedPreferences**, which often store user tokens, feature flags, configuration options, and more. - -Key capabilities include: - -- Browsing all preference files -- Viewing and filtering key-value pairs -- Inspecting primitive values and JSON structures -- **Editing values on the fly** from the desktop UI - -This is an extremely powerful way to test different user scenarios or simulate app states, without needing to rebuild the app or manually trigger edge cases. - ---- - -### 🧩 Database (kotlin multi platform compatible) - -Screenshot 2025-10-14 at 23 40 58 - -Screenshot 2025-10-14 at 23 44 16 - -Flocon gives you direct access to your app’s **local databases** (SQLite, Room, etc.), with a clean interface for exploring and querying data. - -Features include: - -- Listing all available databases -- Display all database tables & schemas -- Running **custom SQL queries** in tabs -- Auto update queries -- Save queries as favorite -- Generate Insert & Delete queries - - -This makes it easy to debug persistent storage issues, verify migrations, or test app behavior with specific data sets — all without leaving your IDE. - -On android there's nothing to add, but on a multi platform project, you need to provide the database's path to flocon - -```kotlin -// on a desktop project -val dbFile = File(System.getProperty("java.io.tmpdir"), "flocon_food_database.db") - -floconRegisterDatabase( - displayName = "food", - absolutePath = dbFile.absolutePath, -) - -return Room.databaseBuilder( - name = dbFile.absolutePath, - ) - .setDriver(BundledSQLiteDriver()) - .setQueryCoroutineContext(Dispatchers.IO) - .build() -``` - - -```kotlin -// on an ios project -val dbFile = "${documentDirectory()}/dog_database.db" - -floconRegisterDatabase( - absolutePath = dbFile, - displayName = "Dog Database" -) - -return Room.databaseBuilder( - name = dbFile, - ) - .setDriver(NativeSQLiteDriver()) - .build() -``` - ---- - -### 📁 File Explorer (android only) - -Screenshot 2025-09-12 at 15 41 20 - -Flocon allows you to explore the **internal file storage** of your Android application — something that typically requires ADB and knowledge of Android's file system. - -From the desktop app, you can: - -- Browse directories within the app's sandbox -- View file metadata (size, modification date, path) -- Open or download files for inspection - -This feature is ideal for inspecting log files, cache data, downloaded assets, or exported config files. - ---- - -### 📈 Configurable Dashboards (from the mobile app) - -Screenshot 2025-09-12 at 15 45 05 -Screenshot 2025-09-12 at 15 44 57 - -Your Android application can define and expose **custom dashboards**, which Flocon renders dynamically in the desktop interface. - -Use cases include: - -- Displaying live business metrics -- Monitoring app state variables -- Debugging real-time values (e.g., geolocation, battery, app mode) -- Real time in-app variables editions -- Perform from the desktop app mobile callbacks - -Dashboards are defined programmatically on the mobile side via the SDK, and they update live as data changes — making them ideal for live demos, QA testing, or in-field diagnostics. - -```kotlin -floconDashboard(id = "main") { - section(name = "User", userStateFlow) { user -> - text(label = "username", value = user.userName) - text(label = "fullName", value = user.fullName, color = Color.Red.toArgb()) - text(label = "user id", value = user.id) - button( - text = "Change User Id", - id = "changeUserId", - onClick = { - updateUser { it.copy(userName = "__flo__") } - } - ) - textField( - label = "Update Name", - placeHolder = "name", - id = "changeUserName", - value = user.fullName, - onSubmitted = { value -> - updateUser { it.copy(fullName = value) } - } - ) - } -} -``` - ---- - -### 📋 Configurable Data Tables (kotlin multi platform compatible) - -tables - -In addition to dashboards, Flocon supports structured **data tables** that can be configured and updated by the mobile app. - -These tables can be used to visualize: - -- Lists of active users -- Items in memory or cache -- Custom logs or metrics -- Backend response simulations - -Tables are interactive, scrollable, and they give developers and testers a straightforward way to inspect lists or collections in real time. - -To create a dynamic row : -```kotlin -floconTable("analytics").log( - "name" toParam "nameValue", - "value1" toParam "value1Value", - "value2" toParam "value2Value", -) -``` - ---- - -### 🔗 Deeplink Launcher (android only) - -Screenshot 2025-09-12 at 15 41 39 - -Flocon includes a **deeplink runner**, which lists all the deeplinks supported by your app (either auto-discovered or manually registered). - -From the desktop UI, you can: - -- Browse available deeplinks -- Enter parameters interactively -- Execute deeplinks directly on the device -- Instantly navigate to specific app screens - -No more typing long `adb shell am start` commands — Flocon makes deeplink testing accessible and efficient. - -**You can configure deeplinks directly from your android code !** -```kotlin -Flocon.deeplinks( - listOf( - Deeplink("flocon://home"), - Deeplink("flocon://test"), - Deeplink( - "flocon://user/[userId]", - label = "User" - ), - Deeplink( - "flocon://post/[postId]?comment=[commentText]", - label = "Post", - description = "Open a post and send a comment" - ), - ) - ) -``` - ---- - -# Grpc - -Similar to network inteceptions, Flocon works with grpc - -it works with `io.grpc:grpc-android` : https://github.com/grpc/grpc-java - -> [!WARNING] -> please ensure your version is at lease `1.70.0` - -[![Maven Central](https://img.shields.io/maven-central/v/io.github.openflocon/flocon-grpc-interceptor.svg)](https://search.maven.org/artifact/io.github.openflocon/flocon-grpc-interceptor) - -> [!IMPORTANT] -> While dealing with protobuf on Android projects, it's best to use its lighter artifact (protobuf-javalite or protobuf-kotlin-lite). -> It might be that your project needs the larger protobuf version (protobuf-java or protobuf-kotlin). -> Flocon offers two interceptor artifacts that leverage a different JSON formatter. It declutters the JSON printing by removing unwanted fields with a dedicated formatter depending on the protobuf library. -> Make sure you choose the correct artifact. - -``` - // If you're using protobuf-javalite or protobuf-kotlin-lite -implementation("com.google.protobuf:protobuf-kotlin-lite:$PROTOBUF_VERSION") - -implementation("io.github.openflocon:grpc-interceptor-lite:LAST_VERSION") -``` -or -``` -// If you're using protobuf-java or protobuf-kotlin -implementation("com.google.protobuf:protobuf-java:$PROTOBUF_VERSION") - -implementation("io.github.openflocon:grpc-interceptor:LAST_VERSION") -``` - - -```kotlin -ManagedChannelBuilder - ... - .intercept( - FloconGrpcInterceptor() - ) - .build() -``` - -## ✨ Upcoming features - -Flocon is still evolving, next features : - -- Preview & Download files - ## 🧰 Requirements -### for android -- An Android device with USB debugging enabled -- Android Studio or SDK tools installed -- ADB (Android Debug Bridge) accessible from your system path +- **Android**: Device/Emulator with USB debugging + ADB. +- **KMP**: Kotlin 2.0.0+ in your app. +- **Desktop**: Flocon Desktop app (JVM-based). -### for all platforms -- Flocon Desktop app (JVM-based) -- Flocon SDK integrated into your app -- At least `kotlin 2.0.0` in your app -- Be aligned between the mobile library version & the desktop app version +For detailed platform-specific requirements, see the [Setup Guide](https://openflocon.github.io/Flocon/setup). --- -## How to install the macOs app ? - -MacOS may block the first launch of the application because it was not downloaded from the App Store. You'll need to manually authorize it through your system settings. - -1. First, try to launch the app from the Applications folder. macOS will display a message stating that it cannot be opened. - - - -2. Click on the `?` on top right of the dialog - - - -3. On the system help page, click on the link "Open privacy & Security for me" - - - -4. Scroll down to the Security section. You should see a message mentioning the blocked application with an `Open Anyway` button. - - - -5. Click on this button 😂 - -6. It opens again the first dialog, but with an additional button in the middle `Open Anyway` - - - -7. Click on this button 😂 (it should ask you a password or fingerprint verification) - -## 🚨 Why Flocon Can’t See Your Device Calls (And How to Fix It) 🚨 - -To enable Flocon to intercept and inspect network traffic from your Android app, -the app must be allowed to connect to `localhost` (typically `127.0.0.1`), which is where the desktop companion listens for traffic. - -**If you're already using a custom `networkSecurityConfig`, make sure it includes a rule to allow cleartext traffic to `localhost`** - -AndroidManifest.xml -```xml - -``` - -network_security_config.xml -```xml - - - - localhost - 127.0.0.1 - - -``` - ## 🤝 Contributors Thanks to these amazing people for making Flocon better every day! - - - - - - - - - - - - - - -
- - Florent Champigny
- florent37 - - 		- - Raphael Teyssandier
- rteyssandier - - 		- - Wouter van der Velde
- Woutervdvelde - - 		- - Gustavo de Santos Garcia
- gdesantos - - 		- - Quentin HUET
- Karambar - -
- - Sebastian Neubauer
- snappdevelopment - - 		- - Simon Marquis
- SimonMarquis - - 		- - Stephen Vinouze
- StephenVinouze - - 		- - Mothana Dabash
- mdabash - -
+[See all contributors](https://openflocon.github.io/Flocon/contributors) -## 🐶 Why the name "Flocon" ✨ ? - -I was looking for a short, cute animal-inspired name — something in the spirit of "Flipper". -I turned my head and saw my golden retriever, Flocon, smiling to me... and that was it. -That was all the inspiration I needed. - -No brainstorming, no hesitation — just the perfect name at the perfect time. - -Flocon - Golden Retriever - -## Contributions - -`The project is open to contributions — feel free to submit a pull request!` +--- ## License