How do I add TapCub to a HarmonyOS app?

Short answer

Register your app's bundleName under App analytics › Configuration › SDK code, add @tapcub/harmony to your project, call TapCub.preInit(this.context, { siteKey: 'YOUR_SITE_KEY' }) in EntryAbility.onCreate (or AbilityStage.onCreate), and await TapCub.init() once the user has accepted your privacy policy. Launches, sessions, router and Navigation page views, and crashes are then collected automatically. Clicks are reported with TapCub.trackClick.

The SDK supports HarmonyOS NEXT (API 12 and later, Stage model) and ships as a HAR.

1. Register the bundleName

Open App analytics › Configuration › SDK code and click Add app identifier. Enter your app's bundleName. Data from a bundleName that is not registered is dropped by the collector.

2. Add the package

The package name is @tapcub/harmony. It is not yet on the OHPM central repository. Until it is, clone the public tapcub-sdk repository and reference the package by a local path in your project's oh-package.json5:

"dependencies": {
  "@tapcub/harmony": "file:../path/to/tapcub-sdk/packages/harmony"
}

Then run ohpm install. Once the package is published, ohpm install @tapcub/harmony will replace the local path; if the console snippet shows a different command, use that.

If your app enables property obfuscation, add this line to obfuscation-rules.txt:

-keep ./oh_modules/@tapcub/harmony

3. Initialize

import { TapCub } from '@tapcub/harmony';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    TapCub.preInit(this.context, { siteKey: 'YOUR_SITE_KEY' });
  }
}

// after the user accepts the privacy policy
await TapCub.init();

• preInit only stores the config and binds the lifecycle: no collection, no device reads, no network. It must run in AbilityStage.onCreate or EntryAbility.onCreate; otherwise the cold start and the first page are lost.
• If your app does not need a consent step, call init right after preInit.
• appId, appVersion and appBuild default to bundleName, versionName and versionCode.
• For China mode, pass region: 'cn', call init after consent and then TapCub.grantConsent(['analytics']).

4. What is collected automatically

ArkUI has no public global click interceptor, so clicks are not automatic. Report them from the component:

Button('Buy now').onClick(() => {
  TapCub.trackClick('buy', 'Buy now');
});

TapCub.ignoreScreen('Splash') skips a page. Frame-rate and memory sampling are not available on HarmonyOS yet.

5. Events and identity

TapCub.track('purchase', { revenue: 19.9, currency: 'CNY' });
TapCub.trackScreen('Checkout');

TapCub.login('USER_ID');
TapCub.setProps({ plan: 'pro' });
TapCub.logout();

The third login argument is the identifier type (default 'login'); 'email' and 'mobile' are hashed first. login is ignored when the project is not in identified mode. See Identify users.

6. Verify

Run the app on a device or emulator and open App analytics › Overview › Realtime. A start event should appear within seconds.

Privacy and storage

The SDK declares only ohos.permission.INTERNET and reads the network type only if your app declares GET_NETWORK_INFO. It does not access location, contacts or the clipboard. The device ID is based on the ODID (shared by one developer's apps, reset by a factory reset). Queued events are stored as files in the sandbox (8 MB, 10,000 events or 7 days by default).

Troubleshooting

• TapCub.preInit(context, config) first: a call ran before preInit.
• siteKey required: the site key is empty.
• No data: bundleName not registered, or init never called.
• No clicks: add trackClick in onClick handlers.
• Stop collection for a user: TapCub.optOut(); optIn() resumes.

Related

• Track screen views
• Install the Android SDK
• Crash-free rate