Showroom Visualizer

A powerful, flexible 360° virtual tour visualizer với Headless Architecture support.

✨ Features

- 🎨 Flexible UI: Sử dụng default UI hoặc build custom UI hoàn toàn
- 🔧 Headless Hooks: Full control với React hooks
- 📦 Component Library: Reusable components để compose custom layouts
- 🎯 Type-safe: Full TypeScript support
- ⚡ Performance: Optimized với React best practices
- 🔄 Backwards Compatible: Code cũ vẫn hoạt động bình thường

📖 Documentation

- Headless API Documentation - Chi tiết về API và hooks
- Examples - 9+ examples từ basic đến advanced

🚀 Quick Start

$3

``tsx
import { ShowroomVisualizer } from 'showroom-visualizer';

function App() {
return (
config={{ tourCode: 'my-tour' }}
mobile={false}
apiHost="https://api.clik.vn/vt360"
/>
);
}
`

$3

`tsx
import { ShowroomVisualizer, useShowroomControls } from 'showroom-visualizer';

function CustomUI() {
const controls = useShowroomControls();

return (


);
}

function App() {
return (
config={{ tourCode: 'my-tour' }}
customLayout={}
/>
);
}
`

$3

`tsx
import { ShowroomVisualizer, useShowroomControls } from 'showroom-visualizer';

function ExternalControls() {
const controls = useShowroomControls();
return

;
}

function App() {
return (
<>

config={{ tourCode: 'my-tour' }}
disableDefaultUI={true}
/>

);
}
`

📚 API Reference

$3

- useShowroomControls() - Main hook với tất cả controls
- useTourCore() - Tour engine state (read-only)
- useSceneNavigation() - Scene navigation controls
- useFloorplanControl() - Floorplan/minimap controls
- useScenarioControl() - Scenario auto-play controls
- usePOIInteraction() - POI interaction controls
- useViewportControl() - Viewport/camera controls

$3

- DefaultLayout - Default UI layout
- PinActions, Floorplan, SceneCategories
- PlayBar, GalleryFullScreen, ModalPopupPoi
- ...và nhiều components khác

Xem HEADLESS_API.md để biết chi tiết.

🎓 Examples

Xem EXAMPLES.md để xem 9+ examples:
- Simple Custom Header
- Scene Grid Selector
- Sidebar Navigation
- External Dashboard
- Auto-play Controls
- POI Explorer
- Complete Custom UI
- Mobile-first UI
- ...và nhiều hơn nữa!

🔧 Development

`bash


Install dependencies

yarn install

Run development server

yarn dev

Build for production

yarn build

Serve built files

serve dist --cors
`

📝 License

MIT
=======

Installation

`bash
npm install @clikvn/showroom-visualizer


or


yarn add @clikvn/showroom-visualizer
`

Basic Usage

`html





`

Features

- 🌐 360° Virtual Tours - Interactive panoramic experiences powered by Krpano
- 🎯 Points of Interest (POI) - Multiple POI types: Gallery, Video, Sound, Navigation, Texture, Promotions
- 🎬 Automated Scenarios - Guided tour playback with camera movements and narration
- 🗺️ Floorplan/Minimap - Interactive navigation with radar positioning
- 📱 Mobile Optimized - Touch controls and responsive layout for mobile devices
- 🌍 Multi-language - Support for EN, CN, JP, KR, VI
- 🎨 Customizable UI - Theme support and configurable components
- 📊 Comprehensive Analytics - 35+ tracking actions covering all user interactions (see below)

Comprehensive Analytics & Tracking

The library includes a powerful tracking middleware system with 35+ actions covering all user interactions:

`typescript
import ShowroomVisualizer from '@clikvn/showroom-visualizer';

ShowroomVisualizer.initVisualizer({
apiHost: 'https://api.clik.vn',
config: { tourCode: 'TOUR_123' },

// Add tracking middleware
middleware: (event) => {
// Event structure:
// {
// actionName: 'onCardItemClick',
// payload: { itemCode, itemTitle, itemType, sceneCode, ... },
// timestamp: '2025-01-15T10:00:00.000Z',
// metadata: { tourCode, sceneCode, categoryCode }
// }

// Send to your analytics service
analytics.track(event.actionName, event.payload);
},
});
`

$3

Search & Discovery (6 actions)

- Panel open/close, search queries
- Category header clicks (Products, Features, Locations, etc.)
- Promotion actions (show more, auto play)
- Individual scenario clicks

Individual Items (1 universal action covering all types)

- Product clicks
- POI clicks (Information, Features, Brands, Locations, Facilities, Multimedia)
- Feature clicks
- Promotion item clicks

POI Detail Panel (5 actions)

- Open/close, audio playback
- Action buttons (AI Assistant, Save, Audio, Share)
- Tab switching (Gallery, AR, Web Rotate, Info, Specification)
- Gallery item clicks

Scenario Playback (8 actions)

- Scenario start, play/pause
- Skip (next/previous), loop toggle
- Sound toggle, playlist toggle
- Playbar close

Navigation (6 actions)

- Scene group selection
- Floorplan changes
- Minimap expand/minimize
- View scenes button

UI Components (1+ actions)

- Guide open/close
- Other UI interactions

$3

✅ Deep-level tracking - Not just categories, but individual items within each category
✅ Rich payloads - Codes, names, types, and contextual data for every action
✅ User journey mapping - Complete visibility from discovery to engagement
✅ Zero overhead - No performance impact when middleware not configured
✅ Fire-and-forget - Non-blocking, error-safe pattern
✅ Analytics-ready - Easy integration with GA4, Mixpanel, or custom backends

$3

#### Search & Discovery (6 events)

| Event Name | Trigger | Payload |
| ----------------------------------- | --------------------------- | ---------------------------------- |
| onSearchAndDiscoveryClose | Panel closed | {} |
| onSearchAndDiscoverySearch | User types in search | { searchQuery } |
| onSearchAndDiscoveryItemClick | Category header clicked | { itemKey, itemTitle, itemType } |
| onSearchAndDiscoveryScenarioClick | Scenario clicked from panel | { scenarioCode, scenarioName } |
| onPromotionShowMore | Show more button clicked | { totalPromotions } |
| onPromotionAutoPlay | Auto play button clicked | { totalPromotions } |

Categories tracked: HOME, AMENITIES, SCENE, PROMOTION, FEATURES, PRODUCT_LIST, INFORMATION, BRAND, LOCATION, FACILITY, MULTIMEDIA, SWAP_ELEMENT, SCENARIO, PLAYLIST, DISPLAY_HOTSPOT, DETAIL

#### Individual Items - Universal (1 event covering ALL types)

| Event Name | Trigger | Payload |
| ----------------- | ---------------------------------------------- | -------------------------------------------------------------------- |
| onCardItemClick | Any item clicked (product, POI, feature, etc.) | { itemCode, itemTitle, itemType, sceneCode, hotspotCode, isVideo } |

Item types covered: Products, Information POIs, Features, Brands, Locations, Facilities, Multimedia, Swap Elements, Promotions

#### POI Detail Panel (5 events)

| Event Name | Trigger | Payload |
| ------------------------- | ------------------------- | ----------------------------------------------------------- |
| onPoiDetailClose | Detail panel closed | { poiCode, poiName, poiType } |
| onPoiDetailAudioPlay | Audio play button clicked | { poiCode, poiName, poiType } |
| onPoiDetailGalleryClick | Gallery item clicked | { poiCode, poiName, poiType, galleryItemId, galleryType } |
| onPoiDetailActionClick | Action button clicked | { actionKey, productCode, productName, productType } |
| onPoiDetailTabChange | Tab switched | { tabKey, productCode, productName, galleryType } |

Action keys: ai_assistant, save, audio, share
Tab keys: gallery, ar, webRotate, info, specification

#### Scenario Playback (8 events)

| Event Name | Trigger | Payload |
| ---------------------- | -------------------------- | ----------------------------- |
| onStartScenario | Scenario started from list | scenarioCode (string) |
| onPlayBarClose | Playbar closed | { scenarioCode } |
| onPlayListToggle | Playlist toggled | { show } |
| onPlayBarPlayClick | Play button clicked | { scenarioCode } |
| onPlayBarPauseClick | Pause button clicked | { scenarioCode } |
| onPlayBarLoopToggle | Loop toggled | { loop, scenarioCode } |
| onPlayBarSoundToggle | Sound toggled | { playing } |
| onPlayBarSkip | Skip button clicked | { direction, scenarioCode } |

Direction values: 'previous' or 'next'

#### Navigation (6 events)

| Event Name | Trigger | Payload |
| ------------------------- | -------------------------- | ------------------------------------------ |
| onSceneGroupSelected | Scene group selected | { sceneGroupCode, sceneGroupName } |
| onSubSceneGroupSelected | Sub scene group selected | { subSceneGroupCode, subSceneGroupName } |
| onFloorplanViewScenes | View scenes button clicked | {} |
| onFloorplanChange | Floorplan changed | { floorplanCode, floorplanName } |
| onMinimapExpand | Minimap expanded | {} |
| onMinimapMinimize | Minimap minimized | {} |

#### UI Components (1+ events)

| Event Name | Trigger | Payload |
| -------------- | -------------------- | ------- |
| onGuideClose | Guide overlay closed | {} |

$3

Google Analytics 4:

`typescript
middleware: (event) => {
gtag('event', event.actionName, {
event_category: 'showroom',
tour_code: event.metadata?.tourCode,
...event.payload,
});
};
`

Mixpanel:

`typescript
middleware: (event) => {
mixpanel.track(event.actionName, {
tour_code: event.metadata?.tourCode,
...event.payload,
});
};
`

Custom Backend:

`typescript
middleware: async (event) => {
await fetch('/api/analytics', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(event),
});
};
`

> 📚 Detailed Documentation: For complete examples, user journey scenarios, and implementation patterns, see Complete Tracking Guide

Available Listeners

The library provides 21+ event listeners for custom app logic:

| Listener | Description | Payload |
| ----------------------- | --------------------- | ------------------------- |
| POI Events |
| onPoiClicked | POI clicked | POI object |
| onPoiOver | Mouse over POI | POI object |
| onPoiHover | Mouse hovering POI | POI object |
| onPoiOut | Mouse left POI | - |
| onPoiInCenter | POI nearest to center | POI object |
| Scene Events |
| onSceneCompleted | Scene loaded | sceneCode, categoryCode |
| onSceneChanged | Scene navigated | Scene object |
| Scenario Events |
| onStartScenario | Scenario started | scenarioCode |
| onScenarioPaused | Scenario paused | scenarioCode |
| onScenarioEnded | Scenario ended | scenarioCode |
| UI Events |
| onToggleSlideIn | Slide-in toggled | { open, offset } |
| onPlaybarOpen | Playbar opened | - |
| onPlaybarClosed | Playbar closed | - |
| onPinActionClicked | Pin button clicked | Button key string |
| Tour Lifecycle |
| onStartLoadingTour | Tour load started | tourCode |
| onFinishedLoadingTour | Tour load finished | tourCode |
| onLoaded | Tool ready | Tool object |
| onDataLoaded | Tour data loaded | tour, tourData |
| Product Events |
| onAIProductClicked | AI product clicked | Product code |
| onShareProductClicked | Share product clicked | Product code |
| Other Events |
| onChanged | Config changed | Config object |
| onTourSwitchLoaded | Tour switch ready | TourSwitch object |
| onStateChanged | State changed | State values |

Key Differences: Listeners vs Middleware

| Feature | Listeners | Middleware (Tracked Actions) |
| -------------- | ------------------ | ------------------------------ |
| Purpose | Custom app logic | Analytics & tracking |
| When fires | Only if configured | Always (if middleware set) |
| Count | 21+ events | 35+ actions |
| Use case | App functionality | User behavior insights |
| Blocking | Can be blocking | Non-blocking (fire-and-forget) |

Example:

- Use listeners to trigger custom UI updates when a scene changes
- Use middleware to track that scene change in your analytics platform

Both can be used together - listeners for app logic, middleware for analytics!

Configuration Options

`typescript
ShowroomVisualizer.initVisualizer({
// Required
apiHost: string; // API endpoint URL
config: {
tourCode: string; // Tour identifier
language?: string; // 'EN' | 'CN' | 'JP' | 'KR' | 'VI'
};

// Optional
mobile?: boolean; // Mobile mode
onLoaded?: (tool) => void; // Callback when loaded
middleware?: (event) => void; // Analytics tracking
listeners?: { // Event listeners (see table above)
onPoiClicked?: (poi) => void;
onSceneChanged?: (scene) => void;
onStartScenario?: (scenarioCode) => void;
onPinActionClicked?: (key) => void;
onSceneCompleted?: (sceneCode, categoryCode) => void;
// ... 16+ more listeners available
};
});
`

Development

`bash


Development with hot reload

yarn dev

Production build

yarn build

Linting

yarn lint
yarn lint:fix

Code formatting

yarn prettier

Serve built files locally

serve dist --cors
``

Documentation

$3

- CLAUDE.md - Complete architecture overview and development guide
- README.md - This file - Quick start and API reference

$3

- 📚 Complete Tracking Guide - Full reference for all 35+ tracking actions
- 📖 Quick Reference Card - Handy cheat sheet for developers
- 📝 Middleware Architecture - Core middleware system documentation
- 📋 Changes Summary - Implementation details and file list

$3

- Planning/ - Feature planning and specifications
- TEMPLATE.md - Template for new feature planning

License

Proprietary - Clik Vietnam