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
Package	tap-sdk-web · v0.1.0
License	MIT
Status	Not on npm — build or link from source
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

The package is not published to npm. Clone and build:

terminal

git clone https://github.com/TapWithUs/tap-web-sdk.git
cd tap-web-sdk
npm install
npm run build

Link into your app:

terminal

# In the tap-web-sdk directory
npm link

# In your project directory
npm link tap-sdk-web

Or install from a local path:

bash

npm install /path/to/tap-web-sdk

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 'tap-sdk-web';

// 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 'tap-sdk-web';

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 'tap-sdk-web';

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.