rybbit_flutter_sdk 0.3.0

Flutter SDK for Rybbit Analytics. Track screen views, events, errors, and user identification with offline queue, GA4 events, and multi-platform support.

rybbit_flutter_sdk

Flutter SDK for Rybbit — open-source, privacy-friendly web analytics.

---

Track screen views, custom events, errors, and user identification from Flutter apps on all platforms.

Features

• Screen view tracking - automatic via NavigatorObserver or manual
• Custom events - with typed properties
• Automatic error tracking - captures Flutter framework errors, async exceptions, and zone errors
• Manual error tracking - trackError() with stack traces and context
• User identification - identify() with traits, backfills 30 days
• Stable device id - anonymous_id per install, so a changing IP or an app update doesn't split one device into several users
• GA4-style typed events - 23 pre-built methods (e-commerce, auth, engagement, CMS, lead gen)
• Persistent offline queue - Hive-backed, survives app restarts
• App lifecycle tracking - automatic app_open, app_foreground, app_background
• Connectivity monitoring - auto-drains offline queue when back online
• Auto icon upload - automatically uploads app icon to Rybbit dashboard
• All platforms - Android, iOS, macOS, Windows, Linux, Web

Installation

From pub.dev

dependencies:
  rybbit_flutter_sdk: ^0.2.0

From Git

dependencies:
  rybbit_flutter_sdk:
    git:
      url: https://github.com/nks-hub/rybbit-flutter-sdk.git
      ref: main

Quick Start

import 'package:flutter/material.dart';
import 'package:rybbit_flutter_sdk/rybbit_flutter_sdk.dart';

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(),
    ));
  });
}

// Screen view
Rybbit.instance.screenView('/checkout', title: 'Checkout');

// Custom event
Rybbit.instance.event('button_click', properties: {'button': 'cta'});

// Error tracking
Rybbit.instance.trackError(error, stackTrace);

// User identification
Rybbit.instance.identify('user-123', traits: {'plan': 'pro'});

Device identity

Every event carries an anonymous_id. The server hashes it into user_id instead of falling back to a hash of IP + user agent, which on mobile changes with every network switch and app update and turns one phone into several "users".

The SDK generates and persists a UUID on first run, so this works out of the box. Pass your own id when the app already has one — a device hash it sends to its own backend, an install UUID — and analytics stays on the same identifier as your own records:

await Rybbit.init(
  host: 'https://analytics.example.com',
  siteId: 'my-site',
  anonymousId: myDeviceHash,
);

// or later, if the id isn't known at init
Rybbit.instance.setAnonymousId(myDeviceHash);

The id survives restarts, but not a reinstall.

Documentation

• API Reference - Complete API documentation for all classes, methods, and configuration options
• Examples - Practical usage examples: setup, navigation, e-commerce, error handling, testing, and more

Requirements

• Flutter >= 3.10.0
• Dart >= 3.0.0
• Rybbit server with PR #921 merged (adds identified_user_id and traits to funnel step sessions)

Dependencies

http | device_info_plus | package_info_plus | connectivity_plus | hive | path_provider

Related

• Rybbit - Open-source web analytics platform
• @nks-hub/rybbit-ts - TypeScript SDK for web
• rybbit-app - Flutter dashboard for Rybbit

Contributing

Contributions welcome! Please open an issue or pull request.

1. Fork the repo
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

License

GNU General Public License v3.0 - see LICENSE.

---

Developed by NKS Hub | [e-mail]