Vifu SDK
@vifu/sdk is the browser SDK for AI-native games and interactive apps. It lets a game expose safe session context, events, and app-owned actions to the Vifu host. It also provides the single public facade for host-managed runtime resources and approved platform capabilities.
The production scope is intentionally narrow: browser games loaded by Vifu Web or by the iOS WKWebView runtime. Node.js and arbitrary backend integrations are not part of this SDK contract.
Compatibility
| Tool | Protocol | Capability | Runtime |
|---|---|---|---|
@vifu/[email protected] | companion.plugin.v1 | companion.plugin.v1 | Vifu Web iframe, iOS WKWebView |
Mental model
- Context is readable session state, such as the current prompt, score, selected word, lesson step, or scene.
- Command is an app-owned action the companion may ask the experience to run.
- Observation is a compact event or fact the experience reports.
- Signal is a rare moment where the game asks the companion to pay attention.
- Reaction is local feedback from the game after a signal or command.
- Resource is host-managed runtime data or media resolved through
Vifu.resources.*. - Invoke is a request to a host-owned capability such as
vifu.dictionary.lookuporhost.game_state.persist.
Keep companion data compact and player-facing. Do not expose access tokens, hidden answers, private user notes, or implementation details.
Use Vifu.services.* or Vifu.services.invoke(capabilityId, args) for platform capabilities. Do not create raw backend requests, parse runtime tokens, or send custom window.parent.postMessage(...) messages from game code.
The host routes these calls from the manifest's top-level policy sections. Legacy capabilities: ["companion.plugin.v1"] enables companion transport only; it does not enable dictionary, game state, resources, speech, camera, or AI. Under the hood, host-owned calls are served by installed first-party capability packages such as @consenger/plugin-review and @consenger/plugin-local-devices. Each plugin ships a static manifest.json for host inspection, then exports lifecycle hooks and providers from code. Game code sees only the stable SDK facade and canonical capability id.
Canonical service facades include:
| Facade | Capability id |
|---|---|
Vifu.services.gameState.save(slot, state) | vifu.gameState.save |
Vifu.services.gameState.load(slot) | vifu.gameState.load |
Vifu.services.dictionary.lookup(input) | vifu.dictionary.lookup |
Vifu.services.speech.microphone.request(options) | vifu.speech.microphone.request |
Vifu.services.speech.transcribe(input) | vifu.speech.transcribe |
Vifu.services.speech.tts.speak(input) | vifu.speech.tts.speak |
Vifu.services.ai.companion.turn(input) | vifu.ai.companion.turn |
Vifu.services.review.preview(input) | vifu.review.preview |
Vifu.services.review.grade(input) | vifu.review.grade |
Vifu.services.camera.snapshot(input) | vifu.camera.snapshot |
Next pages
- Quickstart shows the minimal install and integration path.
- SDK API Reference documents each public method.
- Manifest Reference documents
companion.plugin.v1. - Troubleshooting covers common runtime issues.