HappyOyster Web SDK Integration Guide

​

0. Minimal Integration Example

import { HappyOysterEngine, isSdkError } from "@happy-oyster/js-sdk";

const engine = new HappyOysterEngine({
  APIHost: "open-platform.example.com",
  model: "happyoyster-1.0-adventure", // Required; Adventure model shown as an example
  logLevel: "warn",
});

engine.updateToken(token);

const videoElement = document.querySelector("video") as HTMLVideoElement;
const travel = engine.createTravel({
  ticket,
  videoElement,
  maxExperienceTimeSec: 90, // Optional, Adventure only: 60 / 90 / 120
});

const offStatus = travel.on("statusChanged", (status) => {
  // Use status to drive loading states, disabled buttons, and player UI.
});

const offError = travel.onError((error) => {
  // Usually log, show a toast, and refresh the token if it has expired.
  if (isSdkError(error)) console.error(error.code, error.message);
});

try {
  await travel.start();
  // Enable controls or Directing input with travel.can(action) after the session is running.
} finally {
  offStatus();
  offError();
  await travel.end();
}

​

1. End-to-End Flow Overview

​

1.1 Participants

​

1.2 Experience Flow

​

1.3 SDK Interaction Subflow (Expanded Stage ⑥)

​

1.3.1 Start a Travel

​

1.3.2 Play in Adventure mode

​

1.3.3 Play in Directing / Acting mode

​

1.4 Application Backend Practices (Summary)

• Keep the primary API Key on the application backend only. The browser should receive only a short-lived token (Demo: POST /server-api/temp-api-key).
• Request Travel credentials through the backend. Authorize the world and user before issuing ticket; do not hard-code or cache it long-term in the frontend.
• Do not issue a credential until the world is ready. Otherwise, enter-travel may fail or provide an incomplete experience.
• Point the application backend and the SDK to the same Open Platform environment. The backend may use a full OpenAPI URL; the SDK's APIHost must be only the bare host, such as open-platform.example.com.

​

2. Core SDK Concepts

idle ──start()──► prepare ──video playable──► running ⇄ paused ──end()──► idle

• Each Engine may have only one active Travel at a time.
• videoElement must be provided to createTravel.
• The QwenCloud temporary API-key token and Travel ticket serve different purposes (see stages ④–⑤ in §1.2 and §3.2).

​

3. Initialization and Token Management

​

3.1 Engine Instantiation

• Configure APIHost as the Open Platform bare host, without https://, a scheme, or a path, such as open-platform.example.com.
• Reuse a HappyOysterEngine for the same APIHost + model. Before switching the host or model, end the active Travel and use an Engine configured for the new target.

• Use logLevel: 'debug' in development and 'warn' or 'none' in production.
• Create the Engine in the session orchestration layer instead of constructing a new one for every start.

• Repeatedly calling new HappyOysterEngine() during rendering or on a hot path.
• Passing a full URL, such as one with https://, or calling SDK backend APIs after omitting APIHost.

​

3.2 Dual-Credential Model

• Prepare both credentials before travel.start().
• The SDK does not persist or automatically refresh the token.

• If the token expires or a heartbeat error is received through onError, request a new token through the application backend and call updateToken.

• Mixing the two credentials.
• Exposing the primary API Key to the application frontend.

​

4. Travel Lifecycle

​

4.1 Create and Start

• Call createTravel({ ticket, videoElement }); ticket is the one-time Travel credential, and videoElement is provided at this point.
• Register statusChanged and onError before await travel.start() so that errors and state changes are always observed.

• Show a connecting UI during prepare to prevent duplicate clicks. Use travelInfoReady to read session metadata early, and use firstFrameGenerated as a first-frame placeholder when available.

• Creating a Travel before the DOM element is ready.

​

4.2 While Running

• Drive the UI from statusChanged: prepare means waiting for video, while running means interaction is available.
• Observe the use cases and preconditions for pause, resume, and rewind (they depend on session capability; rewind also requires the session to be paused and the stream to have stopped).

​

4.3 End and Recreate

• End the session with await travel.end().
• Ensure the previous Travel has ended before creating a new one.
• Call travel.end() during cleanup when the page unloads or the route changes.

• After a failure, use "end → remove listeners → retry from stage ③ or ⑤ in §1.2."
• Request a new Travel credential when retrying if the credential is one-time use.

• Calling createTravel a second time without ending the first Travel; this throws synchronously.
• Leaving the page without cleanup, which leaks RTC resources.

​

5. Video Element and Browser Policies

• Set playsInline on <video> (required on iOS).
• Understand how browser autoplay policies affect autoPlay and muted.

• During prepare, show the first-frame image with an overlay; hide it after the session enters running.
• Configure streamReadyTimeout as needed (default: 15,000 ms), and provide a retry action after a timeout.
• Reserve a fixed aspect ratio for the player container.

• Passing a video element reference before the element is attached to the DOM.
• Leaving the UI interactive while the session is paused or the stream is disconnected.

​

6. Event Subscriptions and Error Handling

​

6.1 Event Subscriptions

• Events belong to Travel, not HappyOysterEngine.
• Save the unsubscribe functions returned by travel.on(...) and travel.onError(...).

• Register and clean up listeners in one place. Remove old listeners before switching Travel sessions.

​

6.2 Error Layers

• Startup failures: travel.start() rejects (enter-travel / RTC / timeout).
• Runtime errors: reported through travel.onError (RTC errors, heartbeat authentication failures, and so on).
• Application backend and Open Platform errors in stages ①–④ of §1.2 are handled by the application layer and do not enter the SDK.

• Catching only start() without listening to onError.
• Registering listeners repeatedly without unsubscribing.

​

7. Sending Instructions: Command and Instruct

​

7.1 sendCommand (Real-Time Control)

await travel.sendCommand({ interaction: "Jump" });

// Keep calling while the control is pressed
void travel.sendCommand({ translation: "Front" });

// Stop moving on release
void travel.sendCommand({ translation: "None" });

• Sending many commands during prepare.
• Using sendCommand for natural-language Directing instructions.

​

7.2 sendInstruct (Directing Instructions)

• a Directing session (2) or an Acting session (3) that is not scriptlist; call await travel.sendInstruct({ content }).

• Verify that content is not empty before sending and prevent duplicate submissions.
• Provide user feedback based on returned fields such as accepted.

​

8. Troubleshooting