# Quickstart

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

Using Claude, Cursor or Copilot? [Connect our docs](https://developer.velvetrituals.com/docs/ai-tools.md) so your assistant writes working Velvet code.

## 1. Get a test key

1. [Sign up](https://developer.velvetrituals.com/signup/) or [log in](https://developer.velvetrituals.com/login/) with your Velvet account.
2. On the [dashboard](https://developer.velvetrituals.com/dashboard/), create your test app: a name, one line on what you're building, the 18+ check and the [developer terms](https://developer.velvetrituals.com/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:

```bash
npm install @velvetrituals/toys
```

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

```html
<script src="https://cdn.jsdelivr.net/npm/@velvetrituals/toys@0.1.0/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

**JavaScript**

```ts
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
```

**Script tag**

```html
<button id="connect">Connect toy</button>
<button id="stop">Stop</button>
<script>
  const { VelvetToys } = window.VelvetToysSDK;
  let toy;
  const ready = VelvetToys.init({
    apiKey: 'vr_pk_test_…',
    baseUrl: 'https://devgateway-api.thinkbeyondcorporate.com/v1', // dev only
  });

  document.getElementById('connect').onclick = async () => {
    toy = await (await ready).connect(); // opens the Bluetooth picker
    await toy.vibrate({ strength: 70, durationMs: 3000 });
  };
  document.getElementById('stop').onclick = () => toy?.stop();
</script>
```

**React**

```tsx
'use client'; // Next.js: the SDK runs in the browser only

import { VelvetToys, type Toy } from '@velvetrituals/toys';
import { useEffect, useRef, useState } from 'react';

export function BuzzButton() {
  const velvet = useRef<VelvetToys | null>(null);
  const [toy, setToy] = useState<Toy | null>(null);

  // Verify the key once, before any click, so connect() keeps the user gesture.
  useEffect(() => {
    VelvetToys.init({ apiKey: 'vr_pk_test_…' }).then((v) => (velvet.current = v));
    return () => void velvet.current?.destroy(); // stops and disconnects the toy
  }, []);

  if (!toy) {
    return <button onClick={async () => setToy(await velvet.current!.connect())}>Connect toy</button>;
  }
  return (
    <>
      <button onClick={() => toy.vibrate({ strength: 70, durationMs: 3000 })}>Buzz</button>
      <button onClick={() => toy.stop()}>Stop</button>
    </>
  );
}
```

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

```ts
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:

```bash
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

- See it all working in [Card Vibe](https://developer.velvetrituals.com/demo/card-vibe/).
- [SDK reference](https://developer.velvetrituals.com/docs/sdk.md) for every call.
- [Safety](https://developer.velvetrituals.com/docs/safety.md) for what the SDK enforces, and what you must do.
