Developer Docs
Embed the Spotlight Experience Picker in your application to let users browse and select interactive experiences. The picker runs inside an iframe and communicates via postMessage — fully isolated, works on any domain.
Add the picker script to your page and call SpotlightPicker.open() with your API key.
<script src="https://scaleflex.cloudimg.io/v7/plugins/scaleflex/experiences-picker/1.0.5/experiences-picker.min.js?vh=511af6&func=proxy"></script>
<script> const picker = SpotlightPicker.open({ apiKey: 'YOUR_API_KEY', onSelect: function(result) { console.log('Selected:', result.experience.name); console.log('Embed code:', result.embedCode.js); }, onCancel: function() { console.log('Picker closed'); } });</script>No npm package needed. Load the script directly from your Spotlight instance:
<script src="https://scaleflex.cloudimg.io/v7/plugins/scaleflex/experiences-picker/1.0.5/experiences-picker.min.js?vh=511af6&func=proxy"></script>The script exposes a global SpotlightPicker object.
Opens the picker. Returns an object with close() and destroy() methods.
| Option | Type | Required | Description |
|---|---|---|---|
| apiKey | string | Yes | Your Spotlight API key |
| types | string[] | No | Filter by experience type. Values: HOTSPOT, SPIN_360, BEFORE_AFTER, TOUR, THREE_D_VIEW |
| theme | 'light' | 'dark' | No | Picker color theme. Defaults to 'light' |
| container | HTMLElement | No | Mount picker inline in this element instead of as a modal |
| onSelect | function | No | Called when user selects an experience. Receives { experience, embedCode } |
| onCancel | function | No | Called when picker is closed without selecting |
| onError | function | No | Called on errors. Receives { message, code? } |
interface SelectResult { experience: { id: string; type: 'HOTSPOT' | 'SPIN_360' | 'BEFORE_AFTER' | 'TOUR' | 'THREE_D_VIEW'; name: string; description: string | null; status: 'PUBLISHED'; thumbnail: string | null; tags: string[]; updatedAt: string; }; embedCode: { js: string; // Ready-to-use JS embed snippet iframe: string; // iframe embed snippet react: string; // React component snippet link: string; // Raw embed URL for custom integrations };}interface ErrorResult { message: string; code?: 'INVALID_API_KEY' | 'MISSING_KEY' | string;}Opens a centered overlay with the picker. Closes on backdrop click, Escape key, or the close button.
const picker = SpotlightPicker.open({ apiKey: 'slx_your_api_key', types: ['HOTSPOT', 'SPIN_360'], theme: 'light', onSelect: function(result) { // Insert the embed code into your page document.getElementById('experience-container') .innerHTML = result.embedCode.js;
// Or use the experience data console.log(result.experience.id); console.log(result.experience.name); console.log(result.experience.type); }, onCancel: function() { console.log('User closed the picker'); }, onError: function(err) { console.error('Picker error:', err.message); }});
// Programmatic closepicker.close();
// Full cleanup (removes iframe + listeners)picker.destroy();Mount the picker inside an existing element instead of a modal overlay.
<div id="picker-container" style="height: 500px;"></div>
<script> SpotlightPicker.open({ apiKey: 'slx_your_api_key', container: document.getElementById('picker-container'), onSelect: function(result) { alert('Selected: ' + result.experience.name); } });</script>Load the picker script and open it from a React component.
import { useEffect, useRef, useCallback } from 'react';
// Load the picker script oncefunction usePickerScript() { const loaded = useRef(false); useEffect(() => { if (loaded.current) return; loaded.current = true; const script = document.createElement('script'); script.src = 'https://scaleflex.cloudimg.io/v7/plugins/scaleflex/experiences-picker/1.0.5/experiences-picker.min.js?vh=511af6&func=proxy'; script.async = true; document.head.appendChild(script); }, []);}
export function ExperiencePicker({ onSelect }) { usePickerScript();
const openPicker = useCallback(() => { if (!window.SpotlightPicker) return;
window.SpotlightPicker.open({ apiKey: process.env.NEXT_PUBLIC_SPOTLIGHT_API_KEY, onSelect: (result) => { onSelect(result); }, }); }, [onSelect]);
return ( <button onClick={openPicker}> Choose Experience </button> );}Restrict the picker to show only certain experience types.
// Only show 360° spinsSpotlightPicker.open({ apiKey: 'slx_your_api_key', types: ['SPIN_360'], onSelect: function(result) { console.log(result.experience); }});
// Show hotspots and before/after onlySpotlightPicker.open({ apiKey: 'slx_your_api_key', types: ['HOTSPOT', 'BEFORE_AFTER'], onSelect: function(result) { console.log(result.experience); }});If you prefer not to use the JS wrapper, you can embed the picker iframe directly and listen for postMessage events. All messages are prefixed with spotlight:picker: to avoid collisions.
| Message Type | Payload | Description |
|---|---|---|
| spotlight:picker:ready | {} | Picker UI has loaded |
| spotlight:picker:select | { experience, embedCode } | User selected an experience |
| spotlight:picker:cancel | {} | User closed the picker |
| spotlight:picker:error | { message, code? } | An error occurred (invalid key, network) |
<iframe id="spotlight-picker" src="https://spotlight.scaleflex.com/picker?key=YOUR_API_KEY&types=HOTSPOT,SPIN_360&theme=light" style="width: 100%; height: 500px; border: none;"></iframe>
<script> var pickerIframe = document.getElementById('spotlight-picker');
window.addEventListener('message', function(event) { // Only accept messages from the picker iframe if (event.source !== pickerIframe.contentWindow) return;
var data = event.data; if (!data || !data.type) return;
switch (data.type) { case 'spotlight:picker:ready': console.log('Picker is ready'); break; case 'spotlight:picker:select': console.log('Selected:', data.payload.experience); console.log('Embed code:', data.payload.embedCode); break; case 'spotlight:picker:cancel': console.log('Picker cancelled'); break; case 'spotlight:picker:error': console.error('Picker error:', data.payload.message); break; } });</script>When embedding the picker iframe directly, these URL parameters control its behavior:
| Param | Required | Default | Description |
|---|---|---|---|
| key | Yes | — | Your API key |
| types | No | all | Comma-separated types to show |
| status | No | PUBLISHED | Experience status filter |
| theme | No | light | light or dark |
Enter your API key to try the picker right here. The key is not stored — it's only used in your browser session.
Enter an API key above to try the live demo
API keys are created in the Spotlight Dashboard under Settings → API Keys. Each key is scoped to a workspace and grants read-only access to published experiences.
The picker runs inside an iframe and communicates solely via postMessage. The JS wrapper filters messages by verifying event.source === iframe.contentWindow.
API keys provide read-only access to published experience metadata (name, type, thumbnail, tags). They do not expose experience configs, user data, or workspace settings.
The picker API endpoint sets Access-Control-Allow-Origin: * to allow cross-origin iframe embedding.