Developer Docs

Connectors

Official plugins and integrations for embedding Spotlight experiences on ecommerce platforms. Each connector uses the same shared infrastructure — the Experience Picker and embed.js — so experiences work identically everywhere.

How Connectors Work

All connectors follow the same pattern. The platform plugin handles settings and editor integration, while Spotlight handles experience selection and rendering:

#	Step	Handled By	What Happens
1	Connect	Platform plugin	Admin enters Spotlight API key, plugin validates via POST /v1/integrations/validate
2	Select	Experience Picker	SpotlightPicker.open() opens the picker modal — browse, search, and select an experience
3	Embed	Platform plugin	Plugin stores the experience ID and renders a <div data-spotlight-embed="..."> container
4	Render	embed.js	Auto-discovers containers, fetches config from GET /v1/embed/:id, renders the experience
5	Track	embed.js	Sends analytics events (views, interactions, clicks) to the Spotlight API

No backend changes needed

Adding Spotlight to a new platform never requires backend changes. The integration endpoints and embed delivery are platform-agnostic — any platform that can render HTML and load a script tag can embed Spotlight experiences.

WordPressComing soon

The official WordPress plugin adds a Gutenberg block and shortcode for embedding experiences on any WordPress or WooCommerce site. No coding required.

The WordPress plugin is coming soon. It will provide a Gutenberg block and shortcode for embedding Spotlight experiences on any WordPress or WooCommerce site.

Installation

Upload the scaleflex-spotlight plugin folder to /wp-content/plugins/
Activate through the Plugins menu
Go to Settings → Spotlight and enter your API key
Click Test Connection to verify

Generate an API key from the Spotlight dashboard under Settings → API Keys. The key starts with slx_.

Gutenberg Block

In the block editor, add a Scaleflex Spotlight block. Click Select Experience to open the picker, choose an experience, and save. The block renders the experience on the frontend automatically.

Use the block's sidebar panel to adjust the container height (default: 600px).

Shortcode

For the classic editor or templates, use the [spotlight] shortcode:

HTML

[spotlight id="your-experience-id" height="600px"]

Attribute	Required	Description
id	Yes	The experience ID from the Spotlight dashboard
height	No	Container height as a CSS value. Default: 600px

Script Loading

The plugin loads embed.js conditionally — only on pages that contain a Spotlight block or shortcode. No performance impact on other pages. The Experience Picker script loads only in the block editor.

ShopifyComing soon

The Shopify app adds Spotlight experiences to your store using the Online Store theme editor. Place experiences on product pages, collection pages, or any custom section.

The Shopify connector is coming soon. It will use Shopify's Theme App Extensions for zero-code storefront integration, with the same Experience Picker for selecting experiences in the Shopify admin.

Planned Features

One-click install from the Shopify App Store
Connect to Spotlight with your API key
Select experiences via the built-in picker
Auto-assign experiences to products using metafields
Theme App Extension blocks for the Online Store editor
Analytics enriched with Shopify context (product, collection, shop)

Custom Integrations

Building a connector for another platform (Wix, Squarespace, custom CMS)? Use the same shared endpoints that power the official connectors.

Integration Endpoints

All endpoints require the x-api-key header with a valid Spotlight API key.

Method	Path	Description
POST	/v1/integrations/validate	Validate the API key and return workspace info with experience counts
POST	/v1/integrations/experiences/:id/embed	Get or create an embed for an experience (idempotent)
GET	/v1/embed/:id	Fetch published experience config for rendering (public, no auth)

Validate Connection

Use the validate endpoint to test the API key and display workspace info in your connector's settings page:

Test connectionbash

curl -X POST https://api.spotlight.scaleflex.com/v1/integrations/validate \
  -H "x-api-key: slx_your_api_key" \
  -H "Content-Type: application/json"

Responsejson

{
  "workspace": {
    "id": "uuid",
    "name": "My Store",
    "projectToken": "my-store-token"
  },
  "experiences": {
    "total": 12,
    "published": 8,
    "countsByType": {
      "HOTSPOT": 4,
      "SPIN_360": 3,
      "BEFORE_AFTER": 1,
      "THREE_D_VIEW": 2
    }
  }
}

Rendering on Your Platform

Once you have the experience ID (from the picker or your own UI), render it by placing a container div and loading embed.js:

Minimal embedHTML

<div data-spotlight-embed="EXPERIENCE_ID" style="min-height: 600px"></div>
<script src="https://scaleflex.cloudimg.io/v7/plugins/scaleflex/spotlight/1.0.13/embed.min.js?vh=59288f&func=proxy"></script>

embed.js auto-discovers all data-spotlight-embed containers on the page, fetches config, loads the correct renderer, and tracks analytics. A MutationObserver handles dynamically inserted containers (SPA navigation, AJAX content, etc.).

Experience Picker

Instead of building your own experience browser, load the picker script and call SpotlightPicker.open():

Open the Experience Pickerjavascript

// Load picker.js from CDN (once)
// <script src="https://scaleflex.cloudimg.io/v7/plugins/scaleflex/experiences-picker/1.0.5/experiences-picker.min.js?vh=511af6&func=proxy"></script>

SpotlightPicker.open({
  apiKey: 'slx_your_api_key',
  apiUrl: 'https://api.spotlight.scaleflex.com',
  onSelect(data) {
    // data = { id, embedId, name, type, thumbnail }
    console.log('Selected:', data.id, data.name);
    // Store data.id and render with data-spotlight-embed
  },
  onClose() {
    console.log('Picker closed');
  },
});