Docs / Walk / JavaScript SDK

JavaScript SDK

walk-embed-sdk.js is a standalone, zero-dependency script. It reads data-* attributes off its own tag, injects a fixed-position transparent iframe, and exposes window.ThreeWalkAvatar for runtime control — plus it re-emits the iframe's postMessage events as document-level CustomEvents so you never touch postMessage directly.

Install

One tag. It auto-mounts on DOM ready unless you set data-auto="false".

<script src="https://three.ws/walk-embed-sdk.js"
        data-avatar="YOUR-AVATAR-UUID"
        data-position="bottom-right"
        data-width="220"
        data-height="320"
        data-env="studio"></script>

Script attributes

Attribute	Values	Default	Description
`data-avatar`	avatar UUID / GLB URL	default avatar	The model to render.
`data-position`	`bottom-right` · `bottom-left` · `top-right` · `top-left`	`bottom-right`	Corner to anchor the floating avatar.
`data-width` / `data-height`	pixels	`220` / `320`	Iframe size.
`data-controls`	`none` · `joystick` · `keyboard`	`none`	Input method. With `none`, clicks pass through to your page.
`data-env`	environment id	`studio`	Scene preset.
`data-autoplay`	`true` / `false`	`true`	Auto-walk so the avatar is never static.
`data-ground`	`true` / `false`	`false`	Show the ground disc. Off by default for floating corner embeds.
`data-orbit`	`true` / `false`	`false`	Allow drag-to-orbit. Off by default for corner embeds.
`data-bg`	`transparent` / hex	`transparent`	Background fill.
`data-z-index`	integer	`2147483640`	Stacking order of the floating container.
`data-auto`	`true` / `false`	`true`	Auto-mount on DOM ready. Set `false` to mount manually.

The `window.ThreeWalkAvatar` API

The SDK exposes this object once it loads. Every method below is real and shipped.

Method	Description
`mount(target?)`	Mount the floating iframe. Idempotent. `target` may be an element or selector; defaults to `<body>`. Returns the container element.
`unmount()`	Remove the iframe and detach listeners.
`setAvatar(id)`	Swap the avatar live (UUID or GLB URL).
`setEnv(env)`	Change the environment preset.
`setMotion(motion)`	Set motion: `'idle'`, `'walk'`, or `'run'`.
`setPosition(pos)`	Re-anchor to a corner (`bottom-right` etc.).
`setSize(w, h)`	Resize the floating container in pixels.
`resetPose()`	Recenter the avatar and reset its facing.
`on(name, cb)`	Subscribe to an event (see below).
`off(name, cb)`	Remove a previously registered listener.
`getOptions()`	Return a read-only snapshot of the current options.

Events

The SDK forwards the iframe's postMessage events two ways: as document-level CustomEvents and through on()/off(). The forwarded names are walk:ready, walk:position, walk:error, and walk:avatarChanged.

// Either listen on the document…
document.addEventListener('walk:ready', (e) => {
  console.log('avatar loaded', e.detail);
});

// …or through the API.
ThreeWalkAvatar.on('walk:position', ({ x, z, motion }) => {
  console.log(`at ${x.toFixed(2)}, ${z.toFixed(2)} — ${motion}`);
});

Runtime control example

const api = window.ThreeWalkAvatar;

api.setPosition('top-right');
api.setSize(180, 260);
api.setEnv('night');
api.setAvatar('NEW-AVATAR-UUID');
api.setMotion('run');

Conversion tracking

On the dedicated walk page (and any surface that boots the full walk runtime), window.ThreeWalkAvatar.track(name, opts?) records a creator-defined conversion event against the current avatar. It posts immediately and powers the funnel in the analytics dashboard.

// name is capped at 64 chars; value is an optional number.
window.ThreeWalkAvatar.track('subscribe', { value: 9 });

track() is provided by the full walk runtime. The lightweight floating-corner SDK focuses on mount and control; for conversion analytics, fire events from a page running the walk runtime.

Manual mounting

<script src="https://three.ws/walk-embed-sdk.js"
        data-auto="false"></script>
<script>
  // mount into a specific container when you're ready
  ThreeWalkAvatar.mount('#avatar-slot');
</script>

Edit this page on GitHub

Previous← Iframe embed NextpostMessage events →