Quickstart

Make a Velvet toy (or the virtual toy) buzz from your own web page in about ten minutes.

1. Get a test key

  1. Sign up or log in with your Velvet account.
  2. On the dashboard, create your test app: a name, one line on what you're building, the 18+ check and the developer terms.
  3. Copy the publishable key (vr_pk_test_…). It's shown once.

A test key works on localhost with no setup. To use it on a real domain, add the domain under Allowed origins.

2. Add the SDK

Install it from npm:

npm install @velvetrituals/toys

Or, with no build step, load it with a <script> tag. It exposes window.VelvetToysSDK:

<script src="https://cdn.jsdelivr.net/npm/@velvetrituals/[email protected]/dist/index.global.js"></script>
<script>
  const { VelvetToys } = window.VelvetToysSDK;
</script>

Pin the version in the URL, as above, so an SDK release never changes your page without you knowing.

3. Connect and vibrate

import { VelvetToys } from '@velvetrituals/toys';

// Verifies your key once at start-up.
const velvet = await VelvetToys.init({
  apiKey: 'vr_pk_test_…',
  // Dev only: point at the dev gateway. Leave it out in production.
  baseUrl: 'https://devgateway-api.thinkbeyondcorporate.com/v1',
});

let toy;

// Must run inside a click handler: the browser opens its Bluetooth picker.
connectButton.onclick = async () => {
  toy = await velvet.connect();
  await toy.vibrate({ strength: 70, durationMs: 3000 });
};

stopButton.onclick = () => toy?.stop(); // always give players a Stop button
▶ Try vibrate in the playground

No toy to hand? Use the virtual toy. Same API, same limits, no Bluetooth:

import { mountVirtualToyWidget } from '@velvetrituals/toys';

const toy = await velvet.connect({ virtual: true, model: 'Eclipse' });
mountVirtualToyWidget(document.querySelector('#toy'), toy);

4. Serve it on localhost

Web Bluetooth needs a secure context, and http://localhost counts. Any static server works:

npx serve .

Before connecting a real toy, close Velvet Vibes on your phone or disconnect the toy there. A toy talks to one app at a time.

Next

Last updated 23 Oct 2026