rybbit-flutter-sdk

Totéž pro Flutter: obrazovky, události, chyby, identifikace uživatele.

Rybbit je otevřená analytika, kterou si jde provozovat na vlastním serveru. Na webu ji obsluhuje skript, který Rybbit sám servíruje, jenže mobilní aplikace žádnou stránku s tím skriptem nemá. Kdo chce ve stejném přehledu vidět i svou aplikaci ve Flutteru, potřebuje knihovnu, která pošle zobrazení obrazovek, události a chyby z telefonu a vypořádá se s tím, co web neřeší: výpadky signálu, aplikace na pozadí a zařízení, které během dne vystřídá několik sítí. Tohle je ta knihovna.

Proč jeden telefon nemá být čtyři uživatelé

Když server nedostane identifikátor zařízení, odvodí uživatele z otisku IP adresy a user agentu. Na webu to stačí, v mobilu ne: telefon mění IP adresu při každém přechodu mezi Wi-Fi a mobilními daty a user agent se mění s každou aktualizací aplikace. V provozu se tak jeden člověk za jediný den objevil pod čtyřmi různými identifikátory. SDK proto od verze 0.3.0 posílá s každou událostí stálé anonymous_id. Vygeneruje si ho při prvním spuštění a uloží, a když aplikace už vlastní identifikátor zařízení má, třeba ten, který posílá svému backendu, převezme analytika ten. Data z Rybbitu se pak dají spárovat s vlastními záznamy. Identifikátor vydrží restart aplikace, přeinstalaci ne.

Druhý problém řeší verze 0.4.0. Neupravený server Rybbit odmítne událost s polem, které nezná, kódem 400, a pole app_version a device_model zná jen server s mobilní úpravou z požadavku #921. SDK to pozná na první odmítnuté události, pošle ji znovu bez těch dvou polí a do konce relace je vynechává. Nastavovat se nic nemusí a server, který pole podporuje, je dostává dál.

Co aplikace dostane

Zobrazení obrazovek bez psaní kódu u každé z nich: stačí přidat RybbitNavigatorObserver do navigátoru. Pro vlastní navigaci je tu ruční screenView().
Chyby, na které by se jinak přišlo z recenzí. Spuštění přes Rybbit.runApp zachytí chyby frameworku Flutter, asynchronní výjimky i chyby v zóně a pošle je do Rybbitu se stopou zásobníku; trackError() přidá ručně ošetřené chyby s kontextem.
Události, které nezmizí v tunelu. Co se nepodaří odeslat, uloží knihovna do fronty v Hive a pošle po obnovení připojení nebo při příštím spuštění. Fronta drží nejvýš 1 000 událostí po dobu sedmi dnů; když se zaplní, zahazují se nejstarší, a událost, která neprojde ani na třetí pokus, se zahodí také. Odesílá se každých deset sekund nebo po dvaceti událostech, podle toho, co nastane dřív. Všechny tyhle hodnoty jdou změnit v init().
Životní cyklus aplikace jako události app_open, app_foreground a app_background, takže je vidět, jak často se uživatelé vracejí.
23 typovaných metod ve stylu GA4 pro e-shop, přihlašování, obsah, formuláře a získávání kontaktů, od trackPurchase po trackNewsletterSubscribe. Názvy událostí a vlastností tak sedí mezi aplikacemi i s webem.
Identifikaci přihlášeného uživatele přes identify() s vlastnostmi jako tarif nebo role. Rybbit k ní dopárovává až 30 dnů zpětně.
Režim dryRun, který místo odesílání jen vypisuje, a režim debug s podrobným logem. Vývojová a testovací sestavení tak produkční data nezanesou.

Jak se zapojí

Inicializace je jedno volání s adresou serveru a identifikátorem webu. Funguje proti vlastní instanci i proti Rybbit Cloudu.

void main() {
  Rybbit.runApp(() async {
    WidgetsFlutterBinding.ensureInitialized();

    await Rybbit.init(
      host: 'https://your-rybbit-instance.com',
      siteId: 'your-site-id',
    );

    runApp(MaterialApp(
      navigatorObservers: [RybbitNavigatorObserver()],
      home: const HomeScreen(),
    ));
  });
}

Rybbit.instance.event('button_click', properties: {'button': 'cta'});
Rybbit.instance.identify('user-123', traits: {'plan': 'pro'});

Údaje o zařízení a verzi aplikace bere knihovna z device_info_plus a package_info_plus, stav sítě z connectivity_plus, odesílá přes balíček http. Od verze 0.4.1 posílá user agent zařízení i v hlavičce požadavku, protože neupravený server podle ní určuje prohlížeč a systém; předtím se aplikace na takovém serveru hlásila bez systému. Kód pro web má vlastní větev bez dart:io, takže se aplikace sestaví i pro prohlížeč.

Vypnutí SDK uprostřed odesílání dřív mohlo shodit hostitelskou aplikaci chybou zavřeného úložiště. Od verze 0.2.5 jde všechno, co sahá na frontu, po jednom řetězu, na který dispose() počká, a případná chyba skončí v logu, ne v aplikaci.

Kde se hodí

Aplikace e-shopu, která chce mít nákupy, košík a hledání ve stejných událostech jako web. Na webu je posílá rybbit-ts se stejnými názvy událostí ve stylu GA4.
Aplikace s vlastním backendem, která už identifikátor zařízení má. Předá ho do anonymousId a analytika i backend mluví o stejném zařízení.
Interní nebo oborová aplikace, jejíž data nemají odcházet k reklamní firmě. Rybbit běží na vlastním serveru a SDK posílá jen na adresu, kterou dostane v init().

Knihovna je mezi závislostmi aplikace Rybbit Mobile, mobilního klienta pro tutéž analytiku.

Stav projektu

Na pub.dev je verze 0.4.1 z 10. října 2026, první veřejná verze 0.2.0 tam vyšla koncem února 2026. Balíček má 140 ze 160 bodů hodnocení pub.dev a pub.dev u něj uvádí Android, iOS, macOS, Windows a Linux. Testy pokrývají frontu, odesílání, údaje o zařízení i události ve stylu GA4 a běží bez sítě. Zvláštní sada se pouští ručně proti skutečnému neupravenému serveru a ověřuje, že událost s mobilními poli na něj dorazí.

Automatické nahrání ikony aplikace do přehledu Rybbitu je od verze 0.2.5 ve výchozím stavu vypnuté. Rybbit ho dovolí jen přihlášenému správci webu, takže z vydané aplikace vracel vždy chybu 403; ikona se nahrává v nastavení webu. Vydání na GitHubu repozitář nemá, verze se vydávají jen na pub.dev a popisuje je CHANGELOG.md.

Jak začít

dependencies:
  rybbit_flutter_sdk: ^0.4.1

Potřeba je Flutter 3.10 nebo novější, Dart 3.0 a server Rybbit, vlastní nebo v cloudu. Popis API a ukázky pro navigaci, e-shop, chyby a testování jsou v adresáři doc/ repozitáře.

Zdrojový kód

Kód je na GitHubu v repozitáři nks-hub/rybbit-flutter-sdk, balíček na pub.dev pod jménem rybbit_flutter_sdk. Licence je GPL-3.0, což je potřeba zvážit u aplikací s uzavřeným kódem. Na pub.dev existuje i balíček rybbit_flutter jiného autora, který s tímhle nesouvisí.

← Zpět na přehled