Developer Docs

Embed Integration

Add interactive Spotlight experiences to any website. Choose between the JS plugin embed (recommended) or an iframe embed for maximum isolation.

JS Plugin Embed

The JS embed uses Scaleflex's native plugins to render experiences directly in your page. This gives the best performance and allows full styling control.

Basic Usage

Each experience has a unique embed snippet available from the dashboard. Copy it from the Embed dialog on any published experience.

Hotspot embed exampleHTML

<!-- Hotspot experience -->
<div
  id="spotlight-hotspot-abc123"
  class="cloudimage-hotspot"
  data-image="https://cdn.scaleflex.it/your-image.jpg"
  data-hotspot-config='{"spots":[...]}'
></div>
<script src="https://cdn.scaleflex.it/plugins/js-cloudimage-hotspot/latest/js-cloudimage-hotspot.min.js"></script>
<script>
  new window.CloudimageHotspot('#spotlight-hotspot-abc123');
</script>

360 Spin embed exampleHTML

<!-- 360 Spin experience -->
<div
  id="spotlight-spin-def456"
  class="cloudimage-360"
  data-folder="https://cdn.scaleflex.it/your-spin-frames/"
  data-filename-x="frame-{index}.jpg"
  data-amount-x="36"
></div>
<script src="https://cdn.scaleflex.it/plugins/js-cloudimage-360-view/latest/js-cloudimage-360-view.min.js"></script>
<script>
  window.CI360.init();
</script>

One-click copy

In the Spotlight Dashboard, click the Embed button on any experience to get the ready-to-paste snippet. No manual configuration needed.

Iframe Embed

The iframe embed renders the experience in a sandboxed frame. Use this when you need full isolation from your page's CSS/JS or when embedding on platforms that restrict inline scripts.

HTML

<iframe
  src="https://spotlight.scaleflex.com/embed/EXPERIENCE_ID"
  width="100%"
  height="500"
  style="border: none;"
  allow="fullscreen"
  loading="lazy"
></iframe>

URL Parameters

Append query parameters to the iframe URL to customize behavior:

Param	Type	Description
autoplay	boolean	Auto-start animations (360 spin, tours). Default: false
theme	'light' \| 'dark'	Force a color theme for the experience UI
branding	boolean	Show or hide Scaleflex branding. Default: true

Responsive Sizing

Both embed types work best with responsive containers. The JS plugins automatically resize to their container width. For iframes, use the aspect-ratio trick:

HTML

<!-- Responsive iframe wrapper -->
<div style="position: relative; width: 100%; aspect-ratio: 16/9;">
  <iframe
    src="https://spotlight.scaleflex.com/embed/EXPERIENCE_ID"
    style="position: absolute; inset: 0; width: 100%; height: 100%; border: none;"
    allow="fullscreen"
    loading="lazy"
  ></iframe>
</div>

Domain Whitelist

For security, you can restrict which domains are allowed to embed your experiences. Configure this in Settings → Embed Defaults in the dashboard.

When a domain whitelist is configured, embed requests from non-whitelisted origins will be blocked with a 403 Forbidden response. Leave the whitelist empty to allow all domains.

Pattern	Matches
example.com	Only example.com (exact match)
*.example.com	Any subdomain of example.com (shop.example.com, www.example.com)
localhost:*	Any port on localhost (development)

JS Embed vs Iframe Embed

Feature	JS Plugin	Iframe
Performance	Best — renders natively	Good — extra frame overhead
Style isolation	None — inherits page CSS	Full — sandboxed
SEO	Content in page DOM	Content included with iframe
Setup complexity	Copy snippet from dashboard	Copy snippet from dashboard
CMS compatibility	Requires script tag support	Works everywhere iframes work