storysplat-viewer 2.4.7 → 2.4.8

package/README.md

@@ -7,13 +7,14 @@ A powerful npm package for embedding and interacting with 3D Gaussian Splatting
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Loading Scenes](#loading-scenes)
-  - [From Scene ID (Live-Linked)](#option-1-from-scene-id-live-linked)
-  - [From JSON File (Version-Controlled)](#option-2-from-json-file-version-controlled)
-  - [From URL](#option-3-from-url)
+  - [From Scene ID (Recommended)](#option-1-from-scene-id-recommended)
+  - [From JSON File (Self-Hosted)](#option-2-from-json-file-self-hosted)
 - [API Reference](#api-reference)
+- [Controlling the Viewer](#controlling-the-viewer)
 - [Configuration Options](#configuration-options)
 - [Events](#events)
 - [React Integration](#react-integration)
+- [Analytics & Tracking](#analytics--tracking)
 - [Troubleshooting](#troubleshooting)
 
 ## Installation
@@ -53,11 +54,11 @@ viewer.on('ready', () => console.log('Viewer ready!'));
 
 ## Loading Scenes
 
-There are three ways to load scenes into the viewer:
+There are two ways to load scenes into the viewer:
 
-### Option 1: From Scene ID (Live-Linked)
+### Option 1: From Scene ID (Recommended)
 
-Best for: Live content that updates when you edit in the StorySplat editor.
+**Best for:** Most use cases. Live content that updates when you edit in the StorySplat editor. Includes automatic view and bandwidth tracking.
 
 ```javascript
 import { createViewerFromSceneId } from 'storysplat-viewer';
@@ -69,16 +70,16 @@ const viewer = await createViewerFromSceneId(
 );
 ```
 
-The scene is fetched from the StorySplat API and always reflects your latest changes.
+The scene is fetched from the StorySplat API and always reflects your latest changes. Views and bandwidth are automatically tracked for analytics.
 
 **Getting your Scene ID:**
 1. Open your scene in the StorySplat editor
 2. Click "Upload" or "Update"
 3. Copy the Scene ID from the "Developer Export" section
 
-### Option 2: From JSON File (Version-Controlled)
+### Option 2: From JSON File (Self-Hosted)
 
-Best for: Production apps where you want version control over scene data.
+**Best for:** Self-hosted scenes where you want full control over the scene data. No tracking.
 
 ```javascript
 import { createViewer } from 'storysplat-viewer';
@@ -96,18 +97,7 @@ const viewer = createViewer(
 3. In the "Developer Export" section, click "Download Scene JSON"
 4. Save the file in your project
 
-### Option 3: From URL
-
-Load scene configuration from any URL:
-
-```javascript
-import { createViewerFromUrl } from 'storysplat-viewer';
-
-const viewer = await createViewerFromUrl(
-  document.getElementById('viewer'),
-  'https://example.com/my-scene.json'
-);
-```
+> **Note:** When using `createViewer` with self-hosted scenes, views and bandwidth are not tracked. Use `createViewerFromSceneId` for StorySplat-hosted scenes to get analytics.
 
 ## API Reference
 
@@ -148,7 +138,7 @@ interface ViewerFromSceneIdOptions {
 
 ### createViewer
 
-Create a viewer from scene data object.
+Create a viewer from scene data object. Use this for self-hosted scenes.
 
 ```typescript
 function createViewer(
@@ -158,17 +148,7 @@ function createViewer(
 ): ViewerInstance
 ```
 
-### createViewerFromUrl
-
-Create a viewer by fetching scene data from a URL.
-
-```typescript
-async function createViewerFromUrl(
-  container: HTMLElement,
-  url: string,
-  options?: ViewerOptions
-): Promise<ViewerInstance>
-```
+> **Note:** `createViewer` does not track views or bandwidth. For StorySplat-hosted scenes, use `createViewerFromSceneId` instead.
 
 ### fetchSceneMeta
 
@@ -384,12 +364,101 @@ try {
 }
 ```
 
+## Controlling the Viewer
+
+The viewer instance provides methods to control playback, navigation, and camera programmatically. This is useful for building custom UI controls outside the viewer.
+
+### External Control Example
+
+```html
+<div id="viewer" style="width: 100%; height: 500px;"></div>
+
+<div id="controls">
+  <button id="prev">Previous</button>
+  <button id="play">Play</button>
+  <button id="pause">Pause</button>
+  <button id="next">Next</button>
+  <span id="waypoint-info"></span>
+</div>
+
+<script type="module">
+import { createViewerFromSceneId } from 'storysplat-viewer';
+
+const viewer = await createViewerFromSceneId(
+  document.getElementById('viewer'),
+  'YOUR_SCENE_ID'
+);
+
+// Navigation
+document.getElementById('prev').onclick = () => viewer.prevWaypoint();
+document.getElementById('next').onclick = () => viewer.nextWaypoint();
+
+// Playback
+document.getElementById('play').onclick = () => viewer.play();
+document.getElementById('pause').onclick = () => viewer.pause();
+
+// Update waypoint display
+viewer.on('waypointChange', ({ index }) => {
+  const total = viewer.getWaypointCount();
+  document.getElementById('waypoint-info').textContent =
+    `Waypoint ${index + 1} of ${total}`;
+});
+
+// Jump to specific waypoint
+function goToWaypoint(index) {
+  viewer.goToWaypoint(index);
+}
+</script>
+```
+
+### Available Control Methods
+
+| Method | Description |
+|--------|-------------|
+| `viewer.play()` | Start auto-playing through waypoints |
+| `viewer.pause()` | Pause auto-play |
+| `viewer.stop()` | Stop and reset to first waypoint |
+| `viewer.isPlaying()` | Check if currently auto-playing |
+| `viewer.nextWaypoint()` | Go to next waypoint |
+| `viewer.prevWaypoint()` | Go to previous waypoint |
+| `viewer.goToWaypoint(index)` | Jump to specific waypoint (0-indexed) |
+| `viewer.getCurrentWaypointIndex()` | Get current waypoint index |
+| `viewer.getWaypointCount()` | Get total number of waypoints |
+| `viewer.setPosition(x, y, z)` | Set camera position |
+| `viewer.setRotation(x, y, z)` | Set camera rotation (Euler angles) |
+| `viewer.getPosition()` | Get current camera position |
+| `viewer.getRotation()` | Get current camera rotation |
+| `viewer.resize()` | Recalculate canvas size (call after container resize) |
+| `viewer.destroy()` | Clean up and remove viewer |
+
+## Analytics & Tracking
+
+When using `createViewerFromSceneId`, the viewer automatically tracks:
+
+- **Views**: Each time a scene is loaded
+- **Bandwidth**: Data transferred when loading StorySplat-hosted files
+
+This data appears in your StorySplat admin dashboard.
+
+### What Gets Tracked
+
+| Scenario | Views | Bandwidth |
+|----------|-------|-----------|
+| `createViewerFromSceneId` with StorySplat-hosted files | Yes | Yes |
+| `createViewerFromSceneId` with self-hosted splat files | Yes | No |
+| `createViewer` (self-hosted scenes) | No | No |
+| iframe embed | Yes | Yes |
+
+### Privacy Note
+
+Tracking only occurs for scenes loaded via `createViewerFromSceneId`. If you use `createViewer` with your own scene data, no data is sent to StorySplat servers.
+
 ## Comparison: Scene ID vs JSON File
 
 | Approach | Best For | Pros | Cons |
 |----------|----------|------|------|
-| **Scene ID** | Live content, CMS | Always latest, no redeploy | Needs internet, API dependency |
-| **JSON File** | Version control, offline | Full control, git-tracked | Manual updates needed |
+| **Scene ID** | Live content, CMS | Always latest, automatic tracking, no redeploy | Needs internet, API dependency |
+| **JSON File** | Self-hosted, offline | Full control, git-tracked, no external dependencies | Manual updates, no analytics |
 
 ## Troubleshooting