tapwithus/tap-web-sdk/tap-getting-started

Tap getting started

Works for both firmware classes. connect() returns TapSDKWeb (classic firmware) or TapSDKWeb2 (framed firmware). Write code that handles both unless the user says which device they have. Do not call these "SDK v1" or "SDK v2".

Devices: Tap Strap, Tap Strap 2, TapXR. TapBand uses the same BLE API and is coming soon (waitlist). It is not for sale yet. Never describe it as unsupported, missing, or buyable. TapXR developer firmware supports the full gesture set (taps, thumb swipes, pinches with hold, fist with hold). Do not invent a firmware version number.

1. Ask the user (once)

• Which device: Tap Strap, Tap Strap 2, or TapXR? (TapBand uses the same API; waitlist if they ask to buy one.)
• Is the Tap turned on and charged?
• Is Tap Manager (or another app) holding the connection? Close it.
• Is the firmware up to date (update it in the Tap Manager app)?
• Which browser: Chrome or Edge? The page must use HTTPS or localhost.

2. Install

npm install @tapwithus/tapsdk

In this repository, build the bundle first:

npm install
npm run build

Browser notes:

• Chrome or Edge. Safari and Firefox do not support Web Bluetooth.
• The page must use HTTPS or localhost.
• connect() calls navigator.bluetooth.requestDevice(). Call it from a button click. The browser blocks the device picker without a user gesture.
• In the same page, connect() first reconnects the Tap you last connected (a disconnected Tap does not show in the picker). For an app with its own UI, add a "Choose device" button that calls connect({ reuseKnownDevice: false }). connect({ device }) and connectToDevice(device) skip the picker for a specific BluetoothDevice.

Reconnect in your own app

Copy the Connect and Choose device pattern from tap-build-an-app ("Connect button and reconnect"). In short: disable both buttons while connect() runs, re-enable them on error and on disconnect, and do not add a reload-time Reconnect button.

3. Connect and listen

Open scripts/quickstart.html from this repository with a local static server after npm run build. In an app, use the same order with import { ... } from '@tapwithus/tapsdk'.

1. const sdk = await connect() from a click handler. This attaches, detects firmware, and starts notifications. There is no start().
2. Register every callback immediately after connect() returns.
3. Enable input:

• TapSDKWeb: await sdk.setInputMode(new InputModeController()). It boots in Text mode, which types into the focused field and sends no tap events to the SDK.
• TapSDKWeb2: setFeature(DeviceFeatures.MODEL_DETECTION, true), then pick a vision model (see the tap-vision-models skill).

1. Keep the page open. Do not navigate away.

4. Callback shapes differ between firmware classes

Normalize with:

function first(value: number | number[]): number {
    return Array.isArray(value) ? value[0] : value;
}

Check the class with isTapSDKWeb2(sdk).

5. Callback rules

• Callbacks run on the Bluetooth notification path. Keep them short. Do not block in them.
• To run async work from a callback, use void sdk.sendVibrationSequence([80]), or put the event on a queue and handle it in requestAnimationFrame (see tap-build-an-app).
• sendVibrationSequence([onMs, offMs, onMs, ...]) gives haptic feedback (10-2550 ms per value, up to 18 values).
• await sdk.getDeviceInfo() reads the name, firmware, and battery.

Troubleshooting

More

• Demo: https://tapwithus.github.io/tap-web-sdk/
• Next skills: tap-tapping, tap-vision-models, tap-imu-motion, tap-raw-sensors, tap-knob, tap-dpad, tap-build-an-app