Skip to content

WordPress Integration Guide

This guide covers how to embed StorySplat 3D scenes in WordPress using the official StorySplat Viewer plugin.

Installation

  1. Go to Plugins → Add New in your WordPress dashboard
  2. Search for "StorySplat Viewer"
  3. Click Install Now, then Activate

Manual Installation

  1. Download the plugin from GitHub
  2. Upload to /wp-content/plugins/storysplat-viewer/
  3. Activate through the Plugins menu

Quick Start

Using the Shortcode

Add this to any post or page:

[storysplat scene="YOUR_SCENE_ID"]

Using the Gutenberg Block

  1. Add a new block in the editor
  2. Search for "StorySplat 3D Scene"
  3. Enter your Scene ID in the block settings

Shortcode Attributes

Attribute Description Default
scene Your StorySplat scene ID (required) -
height Height of the viewer 600px
autoplay Auto-start tour playback false
showui Show navigation controls true
lazyload Show thumbnail first false
class Custom CSS class -
id Custom container ID -

Examples

Basic embed: 

[storysplat scene="f8dc96cf-6fc8-4d11-89bb-36c447c0d060"]

Custom height with autoplay: 

[storysplat scene="f8dc96cf-6fc8-4d11-89bb-36c447c0d060" height="800px" autoplay="true"]

Lazy loading for performance: 

[storysplat scene="f8dc96cf-6fc8-4d11-89bb-36c447c0d060" lazyload="true"]

Full viewport height: 

[storysplat scene="f8dc96cf-6fc8-4d11-89bb-36c447c0d060" height="100vh"]

Gutenberg Block

The StorySplat Gutenberg block provides a visual interface for embedding scenes:

  1. Scene ID - Enter your StorySplat scene ID
  2. Height - Set the viewer height
  3. Auto-play - Toggle automatic tour playback
  4. Show Navigation UI - Toggle navigation controls
  5. Lazy Load - Show thumbnail before loading

The block shows a preview in the editor and renders the full viewer on the frontend.

Settings Page

Configure default settings at Settings → StorySplat Viewer:

  • Default Height - Default viewer height for all embeds
  • Auto-play by Default - Enable autoplay by default
  • Show Navigation UI - Show controls by default

These defaults can be overridden per-shortcode or per-block.

Getting Your Scene ID

  1. Create or edit your scene at storysplat.com
  2. Click "Upload" or "Update" to publish
  3. Find the Scene ID in the "Developer Export" section
  4. Copy and paste into your shortcode or block

Advanced Usage

Custom Styling

Add CSS to customize the viewer container:

.storysplat-viewer-container {
  border-radius: 12px;
  overflow: hidden;
  box-shadow: 0 10px 40px rgba(0,0,0,0.2);
}

JavaScript Integration

Access viewer instances for custom controls:

// Get viewer instance by container ID
const viewer = StorySplatWP.getViewer('storysplat-12345');

// Control playback
viewer.play();
viewer.pause();
viewer.nextWaypoint();

// Listen for events
document.getElementById('storysplat-12345').addEventListener('storysplat:ready', (e) => {
  console.log('Viewer ready:', e.detail.viewer);
});

Multiple Viewers

You can embed multiple scenes on a single page:

[storysplat scene="SCENE_ID_1" id="viewer-1"]
[storysplat scene="SCENE_ID_2" id="viewer-2"]

Performance Tips

  1. Use Lazy Loading - Enable lazyload="true" for below-the-fold content
  2. Limit Per Page - Avoid too many 3D viewers on a single page
  3. Optimize Images - Use optimized thumbnails for lazy loading

Troubleshooting

Scene Not Loading

  • Verify the scene ID is correct
  • Ensure the scene is published and public on StorySplat
  • Check browser console for errors

Blank Container

  • Ensure the container has valid dimensions
  • Check that JavaScript is enabled
  • Verify no conflicting plugins

Performance Issues

  • Enable lazy loading
  • Reduce number of viewers per page
  • Check device WebGL support

Support