react-iframe-game-sdk

Thin, typed React hooks that bridge an iframe-sandboxed game or app to a host-injected browser SDK — device sensors, microphone level, Web Audio, and asset lookup — with automatic React lifecycle cleanup.

Why

Games and interactive apps are often shipped inside a sandboxed iframe. The host page injects a runtime SDK as a <script> tag before your app mounts, exposing a global object (by default window.GameSDK) with namespaces for device sensors, audio, and assets.

You can read that global directly. But inside React you'd have to wire the subscriber APIs to component lifecycle by hand — remembering to unsubscribe on unmount, pushing sensor values into state so re-renders happen, and re-typing the API surface every time. This package does that for you:

1. Cleanup on unmount — useEffect unsubscribes automatically, so sensor and microphone listeners never leak.
2. Reactivity — sensor data flows through useState; your component re-renders when a value changes, no manual setState in callbacks.
3. Type safety — the full SDK surface is typed, so typos in API names are caught at compile time.

The hooks stay deliberately thin — all the heavy lifting (permission gating, lazy audio-engine loading, PostMessage plumbing) already lives in the injected SDK. These hooks only add the React glue.

Install

npm install react-iframe-game-sdk
# or
pnpm add react-iframe-game-sdk
# or
yarn add react-iframe-game-sdk

react (>=18) is a peer dependency.

Usage

useGameSdk — one-shot lifecycle calls

Returns the host SDK object (window.GameSDK by default). Use it for one-shot calls or to reach APIs not covered by the specialized hooks. It throws a clear error if the SDK global is missing (e.g. running outside the host iframe).

import { useGameSdk } from "react-iframe-game-sdk";

function Game() {
  const sdk = useGameSdk();

  // Tell the host the game is ready to play.
  useEffect(() => {
    sdk.ready();
  }, [sdk]);

  return <button onClick={() => sdk.score(10)}>+10</button>;
}

useSensors — device motion & orientation

Subscribes to motion and orientation and exposes the latest values as state. Listeners are cleaned up automatically on unmount.

iOS 13+ permission caveat. On iOS, motion/orientation events will not fire until requestPermissions() has been called from a user-gesture handler (e.g. an onClick). This hook does not auto-request — render a "Tap to enable motion" affordance and call requestPermissions() in its click handler. On Android and desktop the permission gate is a no-op.

import { useSensors } from "react-iframe-game-sdk";

function TiltController() {
  const { motion, orientation, requestPermissions } = useSensors();

  return (
    <div>
      {/* iOS needs a user gesture before motion events start flowing */}
      <button onClick={() => requestPermissions()}>Tap to enable motion</button>

      <p>Tilt γ: {orientation?.gamma?.toFixed(1) ?? "—"}</p>
      <p>Accel x: {motion?.acceleration.x?.toFixed(2) ?? "—"}</p>
    </div>
  );
}

useMicrophone — RMS level & "blow" detection

Subscribes to microphone RMS volume (0..1). The mic stream is not opened until you call start(), so nothing is requested on mount. stop() releases it, and unmounting while active cleans up automatically.

A classic use case is blow detection: a noise floor sits around 0.01–0.03, and a blow into the mic spikes to roughly 0.1–0.4.

import { useEffect } from "react";
import { useMicrophone } from "react-iframe-game-sdk";

function BlowToInflate() {
  const { rms, active, start, stop, error } = useMicrophone();

  // Blow detection: treat a sustained spike above the noise floor as a "blow".
  const isBlowing = rms > 0.1;

  useEffect(() => {
    if (isBlowing) {
      // ...inflate the balloon, extinguish the candle, etc.
    }
  }, [isBlowing]);

  if (error) return <p>Mic error: {error.message}</p>;

  return (
    <div>
      <button onClick={active ? stop : () => start()}>
        {active ? "Stop mic" : "Start mic"}
      </button>
      <meter min={0} max={1} value={rms} />
      {isBlowing && <p>💨 blowing!</p>}
    </div>
  );
}

useAudio — Web Audio playback

Returns the SDK's audio namespace (a Web Audio / audio-engine wrapper) with a stable identity.

import { useAudio } from "react-iframe-game-sdk";

function SoundBoard() {
  const audio = useAudio();

  return (
    <>
      <button onClick={() => audio.sfx("coin")}>Coin</button>
      <button onClick={() => audio.music.play("theme", { loop: true, volume: 0.6 })}>
        Music
      </button>
      <button onClick={() => audio.music.fade("theme", 0, 800)}>Fade out</button>
    </>
  );
}

useAssets — manifest URL lookup

Returns the SDK's assets namespace for resolving asset names to URLs.

import { useAssets } from "react-iframe-game-sdk";

function Hero() {
  const assets = useAssets();
  const src = assets.image("hero") ?? undefined;
  return <img src={src} alt="hero" />;
}

configureGameSdkGlobal — custom global name

By default the hooks read window.GameSDK. If your host injects the SDK under a different property name, call configureGameSdkGlobal once, before any hook runs (e.g. at your app's entry point).

import { configureGameSdkGlobal } from "react-iframe-game-sdk";

// Hooks will now read window.MyHostSDK instead of window.GameSDK.
configureGameSdkGlobal("MyHostSDK");

API reference

Configuration

| Export | Signature | Description | | --- | --- | --- | | configureGameSdkGlobal | (name: string) => void | Set which window property the hooks read the host SDK from. Defaults to "GameSDK". Falls back to the default if passed an empty/non-string value. Call before any hook runs. | | getGameSdkGlobalName | () => string | Returns the currently configured global name. |

Hooks

| Hook | Returns | Notes | | --- | --- | --- | | useGameSdk() | GameSdkRoot | The host SDK object. Stable identity (memoized on mount). Throws a clear error if the global is absent. | | useSensors() | { motion: MotionPayload \| null; orientation: OrientationPayload \| null; requestPermissions: () => Promise<boolean> } | Subscribes to motion + orientation; values flow through state. Auto-cleanup on unmount. See the iOS permission caveat above. | | useMicrophone() | { rms: number; active: boolean; start: () => Promise<void>; stop: () => void; error: Error \| null } | RMS level (0..1). Stream opens only on start(). Repeated start() while active is a no-op. Auto-cleanup on unmount. | | useAudio() | SdkAudio | The audio namespace. Stable identity. | | useAssets() | SdkAssets | The assets namespace. Stable identity. |

Types

All types are exported: GameSdkRoot, SdkSensors, SdkAudio, SdkAssets, SpriteAnimator, MotionPayload, OrientationPayload.

The package also augments the global Window interface with an optional GameSDK?: GameSdkRoot property for convenient typing when a host assigns the default global.

License

MIT © 2026 oratis