How do I add TapCub to a WeChat mini program?

Short answer

Register your mini program's AppID under Mini program analytics › Configuration › SDK code, add https://api.pathclue.com to the mini program's request domain list in the WeChat admin console, install @tapcub/miniprogram and build npm in WeChat DevTools, then call TapCub.preInit({ siteKey, appId }) and TapCub.init() in app.js. Launches, page views and page leave times are collected automatically. Check Mini program analytics › Overview › Realtime for $mp_launch.

1. Register the AppID

Open Mini program analytics › Configuration › SDK code and click Add app identifier. Enter the mini program's AppID (it starts with wx). Data from an AppID that is not registered is dropped by the collector, with no error in the mini program.

2. Allow the collection domain

In the WeChat mini program admin console, go to Development › Development management › Server domain and add this to the request legal domains:

https://api.pathclue.com

Without it, requests never leave the device in production. (In DevTools you may not notice, because domain checks can be turned off there.)

3. Install the SDK

In the mini program project root:

npm install @tapcub/miniprogram

Then in WeChat DevTools choose Tools › Build npm so the package is copied into miniprogram_npm.

4. Initialize

In app.js:

import { TapCub } from '@tapcub/miniprogram/wx';

TapCub.preInit({
  siteKey: 'YOUR_SITE_KEY',
  appId: 'YOUR_APPID',
});

App({
  onLaunch() {
    TapCub.init();
  },
});

• appId must be the registered AppID. The collection address is built in; leave endpoint out unless TapCub gives you a dedicated address.
• preInit hooks the App and Page lifecycles, so you do not need to forward onLaunch or onShow yourself.
• China mode: pass region: 'cn', call init only after the user agrees, and call TapCub.grantConsent(['analytics']), or no events are sent.

5. What is collected automatically

• Cold start: $mp_launch and $mp_show, with the scene value.
• Pages: showing a page sends $mp_view_screen; hiding it sends $mp_page_leave with the time on page.
• Clicks: off by default; pass autoTrack: true to preInit to collect them.

If your framework must not patch the global Page, wrap each page instead:

import { wrapPage } from '@tapcub/miniprogram/wx';
Page(wrapPage({ /* page options */ }));

For custom views, call TapCub.trackScreen('Name').

6. Events and identity

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

TapCub.login(openid, {}, { type: 'openid' });
TapCub.logout();

Event names can be up to 100 characters, with up to 30 custom properties and string values up to 200 characters. Login IDs can be up to 200 characters. To link openid, unionid and your own user ID across mini programs, apps and the website, see Identity on mini programs.

7. Verify

Preview the mini program on a phone (with domain checks on) and open Mini program analytics › Overview › Realtime. $mp_launch should appear within seconds. Then look at scene values under Scenes & sharing › Scenes and pages under Pages & events › Pages.

Privacy

The SDK does not read location, contacts or the clipboard, so it adds no privacy API to your WeChat user privacy guidelines. The local queue holds up to 10,000 events, 7 days or 1 MB. Failed requests (429, 5xx, network errors) back off from 1 second up to 300 seconds while events wait in the queue.

Troubleshooting

• Works in DevTools, nothing in production: the request domain is not in the legal domain list.
• No data at all: AppID not registered, siteKey missing, or init not called (in China mode, before consent).
• No page views on some pages: those pages do not go through the patched Page; use wrapPage or trackScreen.
• login has no effect: the ID is longer than 200 characters or a placeholder value, or the project is not in identified mode.

Related

• Identity on mini programs
• Track screen views
• Check your installation