React Native
This is a pure JavaScript bridge to the @tapcub/app-sdk core. It does not depend on a native module.
Install
The package is packages/react-native and needs react-native 0.72 or newer. It is a source package in this repo. Depend on that directory from the workspace or a local path, then:
import { TapCub } from '@tapcub/react-native';Initialize
import AsyncStorage from '@react-native-async-storage/async-storage';
import { AppState, Dimensions, Platform } from 'react-native';
TapCub.preInit(
{ siteKey: 'YOUR_SITE_KEY', appId: 'com.example.app' },
{ asyncStorage: AsyncStorage, appState: AppState, platform: Platform, dimensions: Dimensions },
);
await TapCub.init();The second argument is the host object; the SDK does not import react-native itself. Without asyncStorage the queue lives in memory only. Without appState foreground and background are not recorded. Without platform events are reported as Android. appId matches the application id registered for iOS and Android. With region: 'cn', call init after consent and call grantConsent(['analytics']). track before preInit throws TapCub.preInit() first.
Pageviews
Pass navigation state to navigationHook. A change in the innermost route name sends one $screen_view; the same name as last time is not sent again:
<NavigationContainer onStateChange={TapCub.navigationHook} />If navigation does not go through a React Navigation container, call TapCub.trackScreen('Home') yourself.
Events
TapCub.track('purchase', { revenue: 19.9 });Identity
TapCub.login(userId, { plan: 'pro' }, { type: 'login' });
TapCub.logout();type may be login, email, mobile, openid, unionid, or custom. The core hashes email and mobile first. See Identify users.
Limits
| Item | Requirement | What it means |
|---|---|---|
| Runtime | 0.72 or newer | Declared as a peer dependency |
| Screen events | Navigation hook | Without the hook, screens are not sent automatically |
| Queue | Pass AsyncStorage | Persistent only with it; caps, backoff, and remote config follow the core |
Errors
An unregistered application id drops the event. The call does not throw a network error. If navigationHook gets a state with no route name, it returns and the screen report stays empty. Stop or resume collection with optOut and optIn. Queue caps, backoff, and remote config are in SDK overview.
Flutter
The plugin forwards calls over MethodChannel('tapcub'), so its behavior equals the native SDK it calls.
Install
flutter pub add tapcub_flutter0.2.0 needs Flutter 3.44 and Dart 3.12 or newer; on older Flutter use tapcub_flutter: ^0.1.0. The native SDKs need no extra setup: iOS uses Swift Package Manager by default and the plugin fetches tapcub-ios. Projects that turned SwiftPM off and use CocoaPods add pod 'TapCub', :git => 'https://github.com/tapcub/tapcub-ios.git', :tag => '0.1.0' inside target 'Runner' do in ios/Podfile. Android depends on com.tapcub:android from Maven Central with no extra setup.
Initialize
await TapCub.preInit(TapCubConfig(
siteKey: 'YOUR_SITE_KEY',
appId: 'com.example.app',
));
await TapCub.init();appId matches the application id registered for the native app. With region: 'cn', call init after consent and call grantConsent(['analytics']). The native SDKs record launch and foreground/background on their own: iOS reads the app state, and on Android the plugin hands the current Activity to the native SDK so the cold start is reported too (com.tapcub:android 0.1.1 or later).
Pageviews
Attach the observer on MaterialApp:
MaterialApp(navigatorObservers: [TapCub.navigatorObserver]);On didPush, didReplace, and didPop the observer reads the route's settings.name. Unnamed routes are skipped, and the same name as last time is not sent again. You can also call TapCub.trackScreen('Home').
Events
await TapCub.track('purchase', {'revenue': 19.9});Identity
await TapCub.login('USER_ID');
await TapCub.logout();type is a named argument, default 'login'. Pass type: 'email' or type: 'mobile' explicitly for those ids. This native version stores setProps as event super properties. See Identify users.
Limits
| Item | Requirement | What it means |
|---|---|---|
| Native library | Compile it too | The plugin does not contain the collection core |
| Route name | Needs settings.name | An unnamed route sends no screen |
| Queue | Follows native | The native SDKs persist the event queue (SQLite on Android, files on iOS). flush asks the native SDK to send now |
Errors
A missing native class fails the channel call. Dart receives a platform exception, not a silent analytics error. An unregistered application id drops the event. If the screen report is empty, start with RouteSettings.name. See iOS.
uni-app
When the H5 target is detected, the package throws. Use client.js there. See JavaScript (client.js).
Install
The package is packages/uni-app. Depend on it from the workspace. This repo does not publish an install command. For automatic routing by target, use the package root:
import { TapCub } from '@tapcub/uni-app';@tapcub/uni-app/mp and @tapcub/uni-app/app only export createTapCub(adapters) for that core, without the routing logic.
Initialize
The second preInit argument is the adapters object; omitting it throws. Mini program targets can build it with mpAdapters exported by @tapcub/miniprogram. App targets need your own implementation.
const core = TapCub.preInit(
{
siteKey: 'YOUR_SITE_KEY',
appId: 'YOUR_APPID',
},
adapters,
);
core.init();preInit returns the selected core, which is also available as TapCub.core. The target is resolved from the target option, then the UNI_PLATFORM environment variable, then uni.getSystemInfoSync(). The result is in TapCub.detect. Register appId as the mini program appid or the app id for that target. With region: 'cn', call init after consent and call grantConsent(['analytics']).
Pageviews
Mini program targets follow page lifecycles and send a view on enter and leave. App targets need trackScreen, or an adapter that forwards page lifecycles. H5 pageviews come from client.js.
Events
TapCub.core.track('purchase', { revenue: 19.9 });Identity
Call login and logout on the core. Arguments match the mini program or app core. login is ignored outside identify mode. See Identify users.
Limits
| Item | Behavior | What it means |
|---|---|---|
| H5 | Not this package | Detection as H5 throws |
| Adapters | Pass them first | Otherwise no core is selected |
| Clicks | Off by default | preInit sets autoTrack to false unless you pass true |
Errors
Calling preInit from an H5 build fails. Use client.js there. Omitting adapters throws uni-app: pass adapters or use /mp / /app entries in the host. An unregistered application id drops the event. A mini program target uses the same queue and backoff as the WeChat entry. An app target uses the @tapcub/app-sdk core, so persistence depends on your storage adapter. Check mini program targets in mini program realtime and app targets in app realtime. See SDK overview.