Web SDK

TypeScript / JavaScript SDK for Tap devices in the browser via Web Bluetooth. Same Controller-mode mental model as the native SDKs.

Package
Browser support
Install
Quick Start
API reference
Input modes
Tap codes
TapXR InputType
Demo

Package

Source	TapWithUs/tap-web-sdk
Demo	tapwithus.github.io/tap-web-sdk
npm	@tapwithus/tapsdk · v0.9.0
License	MIT
Status	Official · npm 0.9.0
Language	TypeScript

Browser support

NOTEWeb Bluetooth works in Chrome (Desktop & Android), Edge, and Opera only. Safari and Firefox are not supported. Serve the page over HTTPS or localhost.

Install

Install the published package from npm:

terminal

npm install @tapwithus/tapsdk

Import from the published package. The package entry is dist/index.js with types dist/index.d.ts:

typescript

import { connect } from '@tapwithus/tapsdk';

Or pin the published version:

bash

npm install @tapwithus/[email protected]

Quick Start

Complete copy-paste from the public README. connect() auto-detects v1 / v2. Controller mode is required for tap events on v1:

app.ts

import {
    connect,
    isTapSDKWeb2,
    InputModeController,
} from '@tapwithus/tapsdk';

// Auto-detects v1 / v2 and returns TapSDKWeb or TapSDKWeb2
const sdk = await connect();

sdk.registerDisconnectionEvents((id) => console.log('Disconnected', id));

if (isTapSDKWeb2(sdk)) {
    sdk.registerTapEvents((id, data) => console.log('Tap', data[0]));
} else {
    sdk.registerTapEvents((id, tapcode) => console.log('Tap', tapcode));
    sdk.registerMouseEvents((id, vx, vy, proximity) => {
        console.log(`Mouse: vx=${vx}, vy=${vy}, proximity=${proximity}`);
    });
    await sdk.setInputMode(new InputModeController());
}

await sdk.sendVibrationSequence([100, 200, 100]);

NOTEDefault boot is Text / HID keyboard. In the browser you get no SDK tap callbacks until Controller mode (or Controller+Text). Switch back to Text when you want normal typing.

API reference

Connection

Method	Description
`connect()`	Auto-detect v1/v2; returns TapSDKWeb or TapSDKWeb2
`TapSDKWeb.isSupported()`	`true` if Web Bluetooth is available
`connect()` / `disconnect()`	Instance connect (device picker) / disconnect
`getPermittedDevices()`	Previously permitted devices (Chrome 85+)
`connectToDevice(device)`	Connect to a specific `BluetoothDevice`

Events

Method	Callback
`registerConnectionEvents`	`(sdk) => void`
`registerDisconnectionEvents`	`(identifier) => void`
`registerTapEvents`	`(identifier, tapcode) => void`
`registerMouseEvents`	`(identifier, vx, vy, proximity[, roll, pitch, yaw]) => void`
`registerAirGestureEvents`	`(identifier, gesture) => void`
`registerAirGestureStateEvents`	`(identifier, mouseMode) => void`
`registerRawDataEvents`	`(identifier, packets) => void`

Control

Method	Description
`getDeviceInfo()`	DIS/BAS + Tap device fields
`setInputMode(mode)`	Text, Controller, ControllerText, Raw
`setInputType(type)`	TapXR: Auto, Mouse, Keyboard
`sendVibrationSequence(durations)`	Haptics — ms array, max 18 values, 10–2550ms

Input modes

typescript

import {
    InputModeText,
    InputModeController,
    InputModeControllerText,
    InputModeRaw,
    FingerAcclSensitivity,
    ImuGyroSensitivity,
    ImuAcclSensitivity,
} from '@tapwithus/tapsdk';

await tap.setInputMode(new InputModeText());
await tap.setInputMode(new InputModeController());
await tap.setInputMode(new InputModeControllerText());
await tap.setInputMode(new InputModeRaw({
    scaled: true,
    fingerAcclSens: FingerAcclSensitivity.G16,
    imuGyroSens: ImuGyroSensitivity.DPS500,
    imuAcclSens: ImuAcclSensitivity.G4,
}));

Tap codes

5-bit bitmask of which fingers tapped:

Finger	Bit value
Thumb	1
Index	2
Middle	4
Ring	8
Pinky	16

Example: tapcode = 3 means Thumb + Index.

TapXR InputType

typescript

import { InputType } from '@tapwithus/tapsdk';

await tap.setInputType(InputType.AUTO);
await tap.setInputType(InputType.MOUSE);
await tap.setInputType(InputType.KEYBOARD);

Demo

Live demo: tapwithus.github.io/tap-web-sdk. Source and README: TapWithUs/tap-web-sdk.