Every official SDK is listed below. Pick one to jump straight to its setup guide.
Mobile
Cross-platform
Support matrix
| Platform | Package / entry | Distribution | Version | Minimum | Autocapture |
|---|---|---|---|---|---|
| Website | client.js | <script> tag | 1.0.0 | See JavaScript (client.js) | Pageviews and more; see JavaScript (client.js) |
| Vue / Nuxt / React / Next.js | No separate package; reuse client.js | Manual | — | — | Same as client.js |
| WeChat / Alipay / Douyin mini programs | @tapcub/miniprogram (entries /wx, /my, /tt) | npm | 0.1.0 | Devtools that can build npm packages | Launch, foreground and background, page view and leave, share, favorite; clicks off by default |
| Android | com.tapcub.TapCub | Maven Central com.tapcub:android | 0.1.1 | minSdk 21 | Launch, foreground and background, Activity screens, clicks, Java crashes; ANRs and native crashes on Android 11+ |
| iOS | TapCub | SPM; CocoaPods from the git source | 0.1.0 | iOS 13 | Launch, foreground and background, UIKit screens, clicks, uncaught exceptions and signal crashes, main-thread freezes |
| HarmonyOS | @tapcub/harmony | Sources in the repo, no ohpm manifest | 0.1.0 | API 12 (as labeled in the console) | Depends on the adapter you implement |
| React Native | @tapcub/react-native | npm | 0.1.0 | react-native ≥ 0.72 | Launch and foreground/background (AppState); React Navigation screens |
| Flutter | tapcub_flutter | pub | 0.2.0 | Dart ≥ 3.12, Flutter ≥ 3.44 | Navigator screens; everything else depends on the native SDK |
| uni-app | @tapcub/uni-app | npm | 0.1.0 | — | Mini program targets match the mini program SDK; app targets depend on the adapter |
| Node.js server | TapCub class (@tapcub/node) | npm | 0.1.0 | Node.js 18 (global fetch) | Not applicable |
| PHP server | TapCub\TapCub | Composer tapcub/tapcub-php | 0.1.0 | PHP 8.0, curl and json extensions | Not applicable |
| Python server | tapcub.TapCub | PyPI tapcub | 0.1.0 | Python 3.8, standard library only | Not applicable |
| Java server | com.tapcub.server.TapCub | Maven Central com.tapcub:tapcub-java | 0.1.0 | Java 11 | Not applicable |
| Go server | package tapcub | github. | 0.1.0 | Go 1.21 | Not applicable |
Platform guides:
- Web: JavaScript (client.js), Vue guide, Nuxt guide, React guide, Next.js guide, Chat widget (widget.js), CMS & site builders
- Mini programs: WeChat mini program, Alipay mini program, Douyin mini program
- Native apps: Android, iOS, HarmonyOS
- Cross-platform: React Native, Flutter, uni-app
- Server: Node.js server SDK, PHP server SDK, Python server SDK, Java server SDK, Go server SDK
tapcub in package names
Package, class, and module names still use the historical identifier tapcub / TapCub (for example @tapcub/miniprogram and com.tapcub:android). Those are the TapCub SDKs. There is no second package line under the TapCub name.
Install commands come from the console
ConsoleApp analyticsConfigurationSDK code and ConsoleMini programsConfigurationSDK code print the install command and an init snippet with your site key and collection host filled in. The package names and versions on this page match those screens.Client SDK capabilities
The mini program SDK has its own JavaScript core. HarmonyOS, React Native, and uni-app app targets reuse the @tapcub/app-sdk core. The Android and iOS native cores are ports of @tapcub/app-sdk and run the same shared test vectors, so all four behave the same for queueing, retry, remote config, and identity (React Native persists only when you pass AsyncStorage). They differ in storage, lifecycle, and crash sources, as the table shows. Flutter only bridges calls, so its behavior equals the native SDK it calls.
| Capability | Mini program / HarmonyOS / React Native / uni-app | Android 0.1.1 | iOS 0.1.0 |
|---|---|---|---|
| Persistent local queue | Yes: chunked local storage, default cap 10,000 events, 7 days, 1 MB | Yes: chunks in SQLite, default cap 10,000 events, 7 days, 8 MB | Yes: one file per chunk in Application Support, excluded from backup, default cap 10,000 events, 7 days, 8 MB |
| Retry | 429 / 5xx / network errors back off from 1 s, cap 300 s; after 10 consecutive failures, switch endpoint when several are configured | Same as the JavaScript core | Same as the JavaScript core |
| Remote config (SDK remote config card) | Applied | Applied | Applied |
| Launch / foreground events | Automatic (React Native needs AppState; HarmonyOS and uni-app app targets come from the adapter) | Automatic (ActivityLifecycleCallbacks; cold start includes launch time) | Automatic (app state notifications; cold start includes launch time) |
| Screen events | Automatic on mini programs; React Native uses navigationHook; others depend on the adapter | Activities automatic; Fragment / Compose / Dialog need trackScreen | UIKit automatic; SwiftUI uses .wcScreen or trackScreen |
| Crashes | Reported when the adapter supplies a crash hook | Automatic: uncaught Java exceptions, reported on the next launch; Android 11+ also reads ANRs and native crashes from ApplicationExitInfo | Automatic: NSException and Mach signals, reported on the next launch; also main-thread freezes ≥ 2 s and MetricKit diagnostics on iOS 14+ |
User profile (setProps) | Writes the user profile | Writes the user profile (use registerSuperProps for event super properties) | Writes the user profile (use registerSuperProps for event super properties) |
Shared client conventions
Two-step init. Every client SDK calls preInit first (store config and bind the lifecycle; no network and no device read), then init after the user accepts the privacy policy (fetch site config, create a device id, start sending). If the site does not require consent, call both at startup.
Register the application id. Non-web uploads use appId (mini program appid, Android applicationId, iOS bundle id, HarmonyOS bundleName) as a source check: the SDK places it in the host portion of the upload URL, and an id that is not registered in the console is dropped silently. Register it with Add app identifier on ConsoleApp analyticsConfigurationSDK code or ConsoleMini programsConfigurationSDK code. The value must match appId at init. React Native and Flutter reuse the iOS / Android application id. uni-app reuses the mini program and app application ids.
Collection host. Set endpoint to the host shown on the SDK code page (host only, no path). The SDK appends /api/v1/pulse for events and /api/v1/pulse/cfg for site config. Samples write this host as .
Plan. Mini program and app uploads require a plan that includes that platform group. The free plan includes the website only. Professional and above include website, mini program, and app. If the plan does not include the platform, the collector drops the upload silently. See Plans & quotas.
Identity and collection tier. A persistent device id and identity calls such as login take effect only when the project is in identify mode (collection tier 3). In anonymous mode the SDK still sends events, but it does not write a device id, and identity calls are ignored. See Privacy choices before you start and Identify users.
China mode. After you pass region: 'cn' at init (the spelling on each platform is on that page), the SDK waits until you grant consent before it collects. Call init only after the user agrees.
Check. After integrating, open ConsoleApp analyticsRealtime or ConsoleMini programsRealtime. A $app_start or $mp_launch event means the path is open.
Shared server protocol
The five server SDKs wrap one endpoint (batching, retries and cleaning are described in Server SDKs): POST /api/v1/track, header Authorization: Bearer plus the API key, body { "events": [ … ] }. Create the key at ConsoleConfigurationSettingsAPI keys. Its scope must include track:write (labeled Server track in the UI). The key starts with wck_ and is shown once, at creation.
https://api.tapcub.com/api/v1/track track:writeEach event object accepts the fields below. A field that is not listed fails validation for the whole batch:
typestringDefault: trackeventstringlogin_idstring | nulllogin_id_typestringDefault: logindevice_idstring | nullidentitiesobjecttimeintegerDefault: receive timeinsert_idstringsession_idstring | nullpropertiesobjectunsetstring[]incrementobjectappendobjectitem_typestringitem_idstringgroupstringcontextobjectLimits and meaning:
- 1–1000 events per request. Each API key may send at most 600 requests per minute; above that the response is 429.
- Query
debug=1: validate only, do not store, and return a result per event.validation_behavior=enforce: reject any event that carries a warning. - Events with
insert_idare deduplicated first-write-wins: duplicates in the same batch, and duplicates of an event already stored within one day, are dropped.track_update/track_overwritefind the stored event byinsert_idand merge or replace properties. - A success body looks like
{ "received": 2, "accepted": 2, "rejected": 0, "events": 2, "results": [] }.resultslists only failed or warned items (index,ok,warnings). - A missing key returns 401
NO_API_KEY. An invalid key, or a key withouttrack:write, returns 401BAD_API_KEY. A body that does not match the shape above returns 400VALIDATION.
How server events fit next to front-end data is in Server-side & merging and Server events & log import. The log-style /api/v1/server/events endpoint is in Server events.
How to choose
- Website only: use
client.js. See JavaScript (client.js). For a single-page framework, follow that framework’s guide for routing. - Mini program: native projects use
@tapcub/miniprogram. uni-app projects use@tapcub/uni-appto pick a core. The H5 target usesclient.jsinstead. - Native app: integrate the iOS and Android SDKs separately. HarmonyOS needs an adapter you implement.
- React Native: use the JavaScript package
@tapcub/react-native. It does not depend on a native module. - Facts that should come from the server, such as orders, payments, and refunds: use a server SDK or call
/api/v1/trackdirectly, and sendinsert_idso retries do not double-count.
More of the choice is in Choose how to connect and Platforms.
Versions and upgrades
The Android SDK is 0.1.1 and the Flutter plugin is 0.2.0; the other client SDKs and the server SDKs are 0.1.0. A project can set a minimum SDK version in SDK remote config. Client SDKs (mini program, HarmonyOS, React Native, uni-app, and the native Android and iOS SDKs) stop sending and raise sdk_outdated when they are below that version. Remote config is documented in Collection controls. Version history is in Changelog.