React Widget SDK

Installation

The React widget SDK is included in the same @yavio/sdk package — import from the /react subpath:

npm install @yavio/sdk

Peer dependencies: react >= 18, react-dom >= 18.

Quick start

import { useYavio } from "@yavio/sdk/react";

function BookingWidget({ userId }: { userId: string }) {
  const yavio = useYavio(); // zero config — auto-detects injected config

  const handleSelect = (room: { type: string }) => {
    yavio.step("room_selected", { roomType: room.type });
  };

  const handleBooking = (booking: { price: number }) => {
    yavio.conversion("booking_completed", {
      value: booking.price,
      currency: "EUR",
    });
  };

  return <div>{/* widget UI */}</div>;
}

How configuration works

The server-side withYavio() proxy automatically injects widget configuration into every tool result. The widget SDK picks it up without any manual setup.

Server-side injection

After each tool handler returns, the proxy:

1. Mints a short-lived JWT via POST /v1/widget-tokens
2. Injects { token, endpoint, traceId, sessionId, sessionSource } into the result's _meta.yavio field — sessionSource (SDK 0.5.4) is how the server derived the session, and the widget stamps it on its events so they count for their session the way the server's do

The project API key never reaches the widget — only the short-lived JWT is forwarded.

Client-side detection

useYavio() resolves configuration from the first available source:

If no configuration is found, the hook returns a no-op instance that silently discards all events.

Using with tool results

When your widget receives a tool result containing _meta.yavio, you can pass it directly to useYavio():

import { useYavio } from "@yavio/sdk/react";

function Widget({ toolResult }: { toolResult: Record<string, unknown> }) {
  // Config is extracted from toolResult._meta.yavio automatically
  const yavio = useYavio(toolResult);

  return <div>{/* widget UI */}</div>;
}

extractWidgetConfig()

For cases where you need to extract the config separately (e.g., to check if it exists before rendering):

import { extractWidgetConfig, useYavio } from "@yavio/sdk/react";

function Widget({ toolResult }: { toolResult: Record<string, unknown> }) {
  const config = extractWidgetConfig(toolResult);
  const yavio = useYavio(config ?? undefined);

  if (!config) {
    return <div>Analytics not available</div>;
  }

  return <div>{/* widget UI */}</div>;
}

extractWidgetConfig() checks for config at .yavio (Skybridge responseMetadata) or ._meta.yavio (raw MCP tool result) and returns a validated WidgetConfig or null.

Noop-to-active upgrade

If the hook is first called without config (e.g., tool result not yet available), it starts in no-op mode. When a valid config arrives on a subsequent render, the hook automatically upgrades to an active widget with a real transport.

function Widget({ toolResult }: { toolResult?: Record<string, unknown> }) {
  // First render: no config → no-op mode
  // After tool result arrives: upgrades to active mode
  const yavio = useYavio(toolResult);

  yavio.track("widget_loaded"); // silently discarded until config arrives
  return <div />;
}

Transport behavior

Auto-captured events

The widget SDK automatically captures these events when initialized:

Auto-capture uses feature detection — unsupported APIs are silently skipped.

Session sharing

Widget events share the server's session ID. The traceId correlates a specific tool call with the widget it spawned, while the shared sessionId ensures session-level analytics (duration, tool count, retention) include both server and widget activity.

Session (ses_xxx) ← shared by server + widget
  ├── Trace 1 (tr_aaa) ← tool_call "search_rooms"
  │   ├── step: "rooms_found"           (source: server)
  │   ├── widget_render                  (source: widget)
  │   └── conversion: "booking_completed" (source: widget)
  └── Trace 2 (tr_bbb) ← tool_call "cancel_booking"

Security

• The widget never receives the project API key
• The JWT is trace-scoped, write-only, and expires after 15 minutes
• window.__YAVIO__ is deleted after reading to reduce XSS exposure
• Events from widget JWTs are rate-limited per token