Flipper: cos'è, funzionalità e applicazione

Cos'è Flipper?

Flipper è una piattaforma di debug open source per applicazioni mobili creata da Facebook (Meta) nel 2018. Il progetto si chiamava originariamente Sonar ed era destinato all'uso interno dell'azienda, ma nel 2019 Meta ha pubblicato il codice sorgente sotto licenza MIT. La piattaforma è composta da due componenti: un'applicazione desktop basata su Electron e un SDK che si integra in progetti Android e iOS.

La principale differenza tra Flipper e altri strumenti di debug è la sua architettura modulare. Invece di un debugger monolitico, lo sviluppatore collega solo i plugin effettivamente necessari nel progetto. Questo riduce il carico sull'applicazione e semplifica l'interfaccia: il debugger mostra esattamente ciò che lo sviluppatore ha scelto. Android Studio fornisce profiler integrati, ma funzionano solo tramite ADB e non offrono lo stesso livello di personalizzazione di Flipper.

Secondo Meta, Flipper è utilizzato in più di 2000 progetti all'interno dell'azienda e supporta l'integrazione con Fresco, Litho, RxJava, Retrofit, OkHttp, Picasso, Realm, SQLite e altre librerie popolari. La piattaforma è compatibile con Android API 16+ e iOS 11+.

Architettura di Flipper: come funziona la comunicazione desktop-dispositivo

L'architettura di Flipper è basata su un modello client-server. L'applicazione desktop funge da server e i dispositivi mobili da client. La connessione viene stabilita tramite USB o TCP/IP, dopodiché inizia lo scambio bidirezionale di messaggi utilizzando il protocollo Flipper basato su WebSocket.

Sul lato Android, la comunicazione è fornita dalla libreria android-client che utilizza ADB per il tunneling del traffico. Il client iOS si connette tramite idb (iOS Device Bridge), uno sviluppo proprietario di Meta per interagire con i dispositivi iOS senza Xcode. All'interno dell'applicazione, ogni plugin si registra in FlipperClient e riceve un proprio canale di comunicazione con la controparte desktop.

Il processo di trasferimento dati funziona come segue: il plugin sul dispositivo invia un evento tramite FlipperClient, il client lo serializza in JSON e lo trasmette via WebSocket al desktop. L'applicazione desktop deserializza il messaggio e lo invia al plugin corrispondente nell'interfaccia. Secondo il blog tecnico di Meta (2024), la latenza di trasmissione dei messaggi è inferiore a 15 millisecondi con connessione USB.

Come installare e configurare Flipper

L'installazione di Flipper consiste in tre passaggi: installare l'applicazione desktop, aggiungere l'SDK al progetto e avviare il debugger. L'applicazione desktop viene scaricata dal sito ufficiale fbflipper.com — sono disponibili build per Windows, macOS e Linux nei formati dmg, exe e AppImage. Dopo l'installazione, l'applicazione rileva automaticamente i dispositivi collegati tramite ADB.

Per un progetto Android, Flipper viene collegato tramite dipendenze in build.gradle. È necessario specificare la versione di Flipper che corrisponde alla versione del client desktop e aggiungere plugin per le librerie utilizzate. Di seguito è riportato un esempio di configurazione per un progetto Kotlin:

// build.gradle (app)
val flipperVersion = "0.265.0"

dependencies {
    debugImplementation("com.facebook.flipper:flipper:$flipperVersion")
    debugImplementation(
        "com.facebook.flipper:flipper-network-plugin:$flipperVersion"
    )
    debugImplementation(
        "com.facebook.flipper:flipper-litho-plugin:$flipperVersion"
    )
}

Dopo la sincronizzazione di Gradle, è necessario inizializzare FlipperClient nella classe Application. L'inizializzazione viene eseguita nella build di debug — la libreria non deve essere collegata nella versione release per evitare di esporre informazioni di debug agli utenti.

class App : Application() {
    override fun onCreate() {
        super.onCreate()
        if (BuildConfig.DEBUG) {
            SoLoader.init(this, false)
            AndroidFlipperClient
                .getInstance(this)
                .addPlugin(NetworkFlipperPlugin())
                .start()
        }
    }
}

Per iOS, Flipper viene aggiunto tramite CocoaPods. Nel Podfile vengono specificati i framework Flipper e FlipperKit, oltre a Flipper-Folly e Flipper-PeerTalk per organizzare il canale di comunicazione. Dopo pod install e l'esecuzione dell'applicazione su un simulatore o dispositivo, il client desktop rileverà automaticamente una nuova sessione.

Verifica della connessione

Dopo aver avviato l'applicazione, apri Flipper desktop — nel pannello di sinistra apparirà un elenco dei dispositivi collegati. Se il dispositivo non viene visualizzato, controlla: se ADB è installato, se il debug USB è abilitato su Android o se il bridge idb è in esecuzione per iOS. Ogni dispositivo viene visualizzato con il nome del modello e la versione del sistema operativo.

Plugin Flipper per Android e iOS

I plugin di Flipper sono estensioni modulari che aggiungono pannelli all'interfaccia desktop per attività specifiche. Meta mantiene plugin ufficiali per le librerie più popolari: Network Plugin per OkHttp e URLSession, Database Plugin per SQLite e Realm, Layout Inspector per la gerarchia delle View, SharedPreferences Plugin e Crash Reporter.

Oltre a quelli ufficiali, esiste un ecosistema di plugin di terze parti sviluppati dalla comunità. Ad esempio, MMKV Plugin per il debug dello storage Tencent MMKV, Redux Debugger per React Native, LeakCanary Plugin per il rilevamento di perdite di memoria. I plugin sono distribuiti tramite Maven Central e CocoaPods e vengono collegati come dipendenze regolari.

Un importante vantaggio di Flipper è la possibilità di scrivere plugin personalizzati. Un plugin è composto da due parti: una parte lato client (in Kotlin o Swift) che si registra nell'applicazione mobile e una parte lato desktop (in TypeScript o JavaScript) che aggiunge un pannello UI all'interfaccia. Meta fornisce un'API per creare plugin personalizzati con supporto per WebSocket e messaggi JSON.

Plugin principali per Android

Debug di rete tramite Flipper

Network Plugin è uno dei plugin Flipper più popolari. Intercetta tutte le richieste HTTP/HTTPS che passano attraverso OkHttp su Android o URLSession su iOS e le visualizza nell'interfaccia desktop in tempo reale. Per ogni richiesta sono disponibili: URL, metodo, codice di stato, intestazioni di richiesta e risposta, corpo della richiesta e della risposta, tempo di esecuzione e dimensione.

Per collegare Network Plugin su Android, è sufficiente aggiungere la dipendenza flipper-network-plugin e passare OkHttpClient al costruttore di NetworkFlipperPlugin. Flipper avvolge automaticamente OkHttpClient in un intercettatore. Su iOS, il plugin di integrazione con URLSession richiede la configurazione tramite FlipperNetworkInterceptor.

val networkPlugin = NetworkFlipperPlugin()
val client = OkHttpClient.Builder()
    .addNetworkInterceptor(networkPlugin)
    .build()

Una caratteristica fondamentale di Network Plugin è il supporto per la ricerca e il filtraggio delle richieste. Lo sviluppatore può filtrare le richieste per URL, metodo, codice di stato o tipo di contenuto. Qualsiasi richiesta può essere forzatamente ritentata dall'interfaccia — utile per testare gli endpoint senza scrivere una richiesta curl separata. Secondo un sondaggio degli sviluppatori Meta (2024), Network Plugin è utilizzato nel 78% dei progetti in cui è installato Flipper.

Debug di database e SharedPreferences

Database Plugin fornisce l'accesso ai database SQLite e Realm direttamente dal client desktop. Lo sviluppatore vede tutte le tabelle, il loro schema e i contenuti in una vista tabellare. È possibile eseguire query SQL arbitrarie e aggiungere, modificare ed eliminare record senza scrivere codice. Questo accelera significativamente il debug degli stati dell'applicazione rispetto all'uso di adb shell.

SharedPreferences Plugin funziona in modo simile: mostra tutte le chiavi e i valori memorizzati in SharedPreferences su Android. La modifica avviene istantaneamente — le modifiche sono immediatamente visibili nell'applicazione. Tuttavia, c'è un'importante limitazione: dopo il riavvio dell'applicazione, Flipper si riconnette e tutte le modifiche apportate tramite il plugin vengono preservate perché vengono applicate direttamente al file SharedPreferences.

Per iOS, l'equivalente è NSUserDefaults Plugin. Funziona con UserDefaults e mostra tutte le coppie chiave-valore salvate. Il plugin supporta la modifica di stringhe, numeri, date e array. Le modifiche vengono applicate istantaneamente poiché Flipper accede a UserDefaults tramite l'interfaccia runtime.

Layout Inspector e registrazione

Layout Inspector di Flipper fornisce una rappresentazione visiva della gerarchia delle View su Android. Lo sviluppatore vede l'albero dei componenti, i loro attributi (larghezza, altezza, padding, sfondo, testo) e può selezionare interattivamente qualsiasi elemento sullo schermo del dispositivo. Questa è un'alternativa al Layout Inspector integrato in Android Studio, ma con una differenza importante — Flipper mostra la gerarchia in tempo reale senza fermare l'applicazione.

Per la registrazione, viene utilizzato il Logs Plugin. Tutti i log da Logcat appaiono nell'interfaccia desktop con filtro per livello (Debug, Info, Warn, Error) e tag. A differenza di Android Studio Logcat, l'interfaccia di Flipper non sovraccarica lo schermo — i log vengono raggruppati per tag ed evidenziati per livello. Sono supportati la ricerca e l'esportazione dei log in JSON.

Un'altra funzionalità utile è Console Plugin, che mostra console.log dal codice JavaScript nei componenti React Native o WebView. Questo semplifica il debug delle applicazioni ibride: lo sviluppatore vede sia i log nativi che i log JS in un'unica interfaccia. Il plugin supporta il filtraggio per sorgente (Native o JS) e livello di registrazione.

Configurazione dei plugin Flutter

Per le applicazioni Flutter, Flipper viene collegato tramite il pacchetto flipper da pub.dev. Il plugin flutter_flipper fornisce l'integrazione con il livello di rete Dio, l'archiviazione SharedPreferences e la navigazione Flutter. L'installazione richiede l'aggiunta della dipendenza a pubspec.yaml e l'inizializzazione di FlipperClient nella funzione main dell'applicazione. I plugin Flutter sono ancora inferiori a quelli nativi in termini di funzionalità, ma coprono i principali scenari di debug.

Prestazioni durante il debug

Flipper consuma risorse del dispositivo e del desktop proporzionalmente al numero di plugin attivi. Quando tutti i plugin sono collegati simultaneamente su un emulatore Android, si osserva un calo delle prestazioni del 5–10% secondo le misurazioni di Meta (2024). Si consiglia di collegare solo i plugin necessari e disabilitare quelli non utilizzati tramite l'interfaccia dell'applicazione desktop.