How do I add TapCub to a Flutter app?

Short answer

Register both your Android applicationId and iOS bundle ID under App analytics › Configuration › SDK code, run flutter pub add tapcub_flutter, call TapCub.preInit and TapCub.init at startup, and add TapCub.navigatorObserver to MaterialApp so named routes are sent as screens. The plugin forwards every call to the native Android and iOS SDKs, so launches, sessions and crashes are collected by them.

Requirements

• tapcub_flutter 0.2.0 needs Flutter 3.44 and Dart 3.12 or newer. On older Flutter, use tapcub_flutter: ^0.1.0.
• iOS uses Swift Package Manager by default; the plugin fetches tapcub-ios automatically.
• Android depends on com.tapcub:android (0.1.1 or later) from Maven Central, with no extra setup.

1. Register both app identifiers

Open App analytics › Configuration › SDK code and click Add app identifier twice: once for the Android applicationId and once for the iOS bundle ID. Data from an identifier that is not registered is dropped silently.

2. Install

flutter pub add tapcub_flutter

If your iOS project has Swift Package Manager turned off and uses CocoaPods, add this inside target 'Runner' do in ios/Podfile, then run pod install:

pod 'TapCub', :git => 'https://github.com/tapcub/tapcub-ios.git', :tag => '0.1.0'

3. Initialize

import 'package:tapcub_flutter/tapcub_flutter.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await TapCub.preInit(TapCubConfig(
    siteKey: 'YOUR_SITE_KEY',
    appId: 'com.example.app',
  ));
  // after the user accepts the privacy policy:
  await TapCub.init();
  runApp(const MyApp());
}

appId must match the identifier registered for the native app. For China mode, pass region: 'cn', call init after consent and then TapCub.grantConsent(['analytics']).

The native SDKs record launches and foreground/background on their own. On Android the plugin hands the current Activity to the native SDK so the cold start is reported too.

4. Track screens

MaterialApp(
  navigatorObservers: [TapCub.navigatorObserver],
  // ...
);

On push, replace and pop the observer reads the route's settings.name and sends a screen view. Unnamed routes are skipped, and the same name as last time is not sent again. Give routes names (RouteSettings(name: 'Checkout') or named routes), or call TapCub.trackScreen('Home') yourself.

5. Events and identity

await TapCub.track('purchase', {'revenue': 19.9, 'currency': 'USD'});

await TapCub.login('USER_ID');       // type defaults to 'login'
await TapCub.login('a@example.com', type: 'email');
await TapCub.logout();

In this version setProps is stored as event super properties. Call TapCub.flush() to ask the native SDK to send queued events now.

6. Verify

Run on an Android emulator and an iOS simulator and open App analytics › Overview › Realtime. Start events should arrive from both platforms within seconds; use the platform filter in the header to separate them.

Troubleshooting

• PlatformException on the first call: the native library is missing from the build. Run a full rebuild (flutter clean, then build again); on CocoaPods projects check the Podfile line.
• No data from one platform: that platform's identifier is not registered.
• No screens: the observer is not on MaterialApp, or routes have no settings.name.
• Queue and retries follow the native SDKs (SQLite on Android, files on iOS).

Related

• Install the Android SDK
• Install the iOS SDK
• Track screen views