Advanced Integration Guide

Embed GLOW's interactive 3D fireworks directly into your product listings and detail pages for an immersive shopping experience that increases engagement and helps sell more fireworks.

This guide will help you integrate GLOW's features seamlessly into your existing UI, giving you maximum flexibility to match your brand and user experience goals.

Troubleshooting

Something not working? Always check your browser's JavaScript console for informative error messages provided by GLOW.

Step 1: Setting Up Product Identifiers for GLOW
Step 2: Load and Initialize the GLOW Library
Step 3: Add Interactive Features
Step 4: Embedding the Show Builder Application
Final Checklist
Promoting the 3D Show Builder
Troubleshooting & Common Errors
Feature Reference

Before You Start

Confirm you can modify the HTML on your site, and are able to create a new dedicated page to embed the GLOW Show Builder.
Ensure you have a valid retailer ID and product IDs from GLOW.

Step 1: Setting Up Product Identifiers for GLOW

The advanced integration involves adding new buttons alongside products on your site, enabling 3D previews and seamless add-to-show functionality. To make this work, you'll need to store product identifiers that GLOW recognizes.

How GLOW Identifies Products

GLOW identifies fireworks using two key values:

Brand ID: A unique string identifier representing the firework brand.
Product ID: A unique string identifier for each firework within that brand.

GLOW provides a list of product IDs based on your catalog, to associate each firework with its 3D simulation. These IDs are typically stored in your database alongside other product information, allowing you to dynamically insert them into your website's product pages.

How to Use IDs on Your Website

When adding buttons to enable GLOW's interactive features, you'll embed these IDs directly into your HTML as data- attributes. Here's a straightforward example for a single product:

HTML
<button class="glow-preview-btn" data-glow-brand-id="sample" data-glow-product-id="demo-500g">
  3D Preview
</button>
<button class="glow-add-btn" data-glow-brand-id="sample" data-glow-product-id="demo-500g">
  Add to Show
</button>

If your HTML doesn't match the above structure, you can customize how GLOW extracts IDs from your buttons.

Custom Filtering

To enhance your product listings, you can implement a filter that displays only 3D-enabled products. By adding this filter alongside your existing search and category controls, you'll help users quickly find supported products for building a show. Since this is a custom feature, you'll need to implement it based on the GLOW product IDs in your database – but we highly recommend it.

No Database? No Problem.

If your site doesn't use a database or product management system, you can still enable GLOW features by manually adding data- attributes to the relevant product buttons – just like in the example above.

Step 2: Load and Initialize the GLOW Library

Include the following <script> tags on any page where you'd like to enable GLOW functionality.

Important

Replace 'your_retailer_id' with the ID provided to you by GLOW, and customize the themeColor to match your branding:

HTML
<script src="https://glowfireworks.com/sdk/js/v1"></script>
<script>
  glow.initialize({
    retailerId: 'your_retailer_id', // TODO: Replace with your retailer ID
    themeColor: '#0082e6'           // TODO: Adjust to match your brand color
  });
</script>

Step 3: Add Interactive Features

The glow.setupInteractions() function simplifies advanced integration of GLOW's interactive features, allowing your users to preview fireworks, add products to their custom shows, and access a floating link to your embedded Show Builder – all without complicated boilerplate code.

Below is a comprehensive example you can copy and paste to enable all interactive features. You might not need every feature shown here – refer to the feature reference for additional details – but in the spirit of "show me the code", here it is:

JavaScript
glow.setupInteractions({
  watchElements: true, // Track dynamically loaded buttons
  preview: {
    buttonSelector: '.glow-preview-btn' // Select buttons for 3D previews
  },
  addToShow: {
    buttonSelector: '.glow-add-btn', // Select buttons for adding products to a show
    handleStatusUpdate: (button, inShow) => {
    	// Update button appearance based on whether the product is added. Customize as needed.
      button.disabled = inShow;
      button.textContent = inShow ? 'In Show' : 'Add to Show';
    }
  },
  // Display a sticky footer link to the Show Builder page after products are added to the show.
  floatingShowBuilderLink: {
    // TODO: Update this URL to point to your Show Builder.
    url: '/show-builder',
    // TODO: Style the sticky footer link to match your website.
    style: {
      bgColor: '#fff',
      linkBgColor: '#0077d3',
      linkBgColorHover: '#348ef0',
      linkTextColor: '#fff',
      linkBorder: 'none',
      linkBorderRadius: '4px'
    }
  }
});

Step 4: Embedding the Show Builder Application

To complete your advanced integration, you'll need to create a dedicated page on your website to embed the GLOW Show Builder application. This is the page customers will visit when reviewing and customizing their firework shows.

Create the Show Builder Page

The floating link feature in the setupInteractions configuration above points to a path like /show-builder. You'll need to create this new page (or use a different path of your choosing) to embed the Show Builder application.

We recommend keeping this page completely empty – no headers, footers, or other elements. The GLOW Show Builder iframe will automatically take over the entire page for the best user experience.

Load the Show Builder Application

On the new Show Builder page, paste the following code in the <body> and update the highlighted lines. This code loads and initializes the GLOW library like we did above, then generates the Show Builder application.

When users visit this page, they'll see the full-page interactive Show Builder application.

Important

The catalogUrl parameter should point to a full URL (starting with https://) on your website where customers can browse your 3D-enabled fireworks. Ideally this is a product listing page with a filter pre-applied that only shows 3D-supported items. The Show Builder will provide navigation links to the provided URL, helping customers easily return and continue shopping.

HTML
<script src="https://glowfireworks.com/sdk/js/v1"></script>
<script>
  glow.initialize({
    retailerId: 'your_retailer_id', // TODO: Replace with your retailer ID
    themeColor: '#0082e6'           // TODO: Adjust to match your brand color
  });

  // TODO: Update the `catalogUrl` value with a correct URL.
  glow.createShowBuilder({ catalogUrl: 'https://your-domain.com/products?3d-enabled=1' });
</script>

Final Checklist

Include the GLOW <script> tag and call glow.initialize() with your retailer ID on every page using our features.
Test all 3D preview and add-to-show buttons, confirming they work as expected.
After adding fireworks, ensure a link appears that navigates to the Show Builder application.
Confirm Show Builder correctly displays the added products.
In the Show Builder application, clicking your logo takes you to an appropriate page on your site to browse 3D products.
Check browser console for GLOW-related errors on any pages using our library.

Promoting the 3D Show Builder

To maximize engagement, it's essential to make the 3D Show Builder easy to discover. We recommend the following promotional strategies:

Add a main navigation link: Include a direct link to the 3D Show Builder in your website's main navigation. This should point to an appropriate page on your site where customers can browse 3D products.
Homepage callout: Feature a high-visibility banner or other callout on your homepage to introduce customers to the 3D Show Builder.
Leverage marketing channels: Promote the experience across social media, email campaigns, and print materials to drive traffic and awareness.

Troubleshooting & Common Errors

Error Messages: GLOW provides clear, actionable error messages in the browser console – always check there first.
Loading the GLOW library more than once? Ensure the library is loaded only once per page/session. If our script tag is included on a page multiple times (which can sometimes happen accidentally with automated script loading setups), an error will be logged to the console and some functionality may not work as expected.
Buttons Not Working? Confirm our script is loaded and glow.initialize() is called before invoking setupInteractions(). Then ensure buttons have valid data-glow-brand-id and data-glow-product-id attributes or a correct custom extraction function.
Calling setupInteractions Multiple Times? Call this method only once per page. Subsequent calls will result in an error logged in the console.

Feature Reference

Below is a detailed breakdown of each available feature in glow.setupInteractions().

Watch Mode

If your page dynamically loads or filters products via AJAX or JavaScript filtering, enable watchElements to keep all buttons active during dynamic DOM updates.

watchElements: true

Performance Impact

Watch mode is convenient, but comes at a small performance cost as it needs to track all potential GLOW-related elements as they come and go. If your site does not dynamically load or filter elements with JavaScript, it's best to disable this feature by setting watchElements: false.

3D Product Previews

Enable inline 3D product previews directly on your product pages. Users click buttons that trigger a modal displaying interactive 3D firework simulations.

Configuration Example:

preview: {
  buttonSelector: '.glow-preview-btn'
}

Add-to-Show Buttons

These buttons let users add fireworks directly to their custom show from your product listing or detail pages. Your UI stays updated automatically, even if users have multiple tabs open.

Configuration Example:

addToShow: {
  buttonSelector: '.glow-add-btn',
  handleStatusUpdate: (button, inShow) => {
    button.disabled = inShow;
    button.textContent = inShow ? 'In Your Show' : 'Add to Show';
  }
  // Optional: Display custom feedback after successfully adding an item
  onSuccess: (button) => {
    // E.g., display a quick toast message or animation
    showToast('Item successfully added to your show!');
  }
}

Understanding the Callbacks:

handleStatusUpdate: Invoked whenever the button's status should update, including:
- Initial page load (to set initial state)
- After adding an item to the show
- When items are added/removed from other tabs or pages
onSuccess (Optional): Called only after a user successfully adds a firework to their show by clicking the button. This is ideal for providing visual or textual confirmation beyond the standard UI update.

Floating Show Builder Link

It's important to provide users quick access to their custom firework show. This feature automatically adds a persistent link at the bottom of your website once a user adds at least one firework, making it easy for them to review and finalize their show.

Configuration Example:

floatingShowBuilderLink: {
  url: '/show-builder', // or https://yourdomain.com/show-builder
  style: {
    bgColor: '#fff',
    linkBgColor: '#0077d3',
    linkBgColorHover: '#348ef0',
    linkTextColor: '#fff',
    linkBorder: 'none',
    linkBorderRadius: '4px'
  }
}

Optional Settings:

linkText: Customize the text displayed on the link (default is "Open Show Builder").
style.zIndex: Control the CSS stacking order of the floating link element if it conflicts visually with other elements on your page (default is 1000).

Here's what it looks like to use these optional settings in your code:

floatingShowBuilderLink: {
  url: '/show-builder',
  linkText: 'Watch Show',
  style: {
    // ...other styles
    zIndex: 99999
  }
}

Build a Custom Footer

The built-in floating link provides a quick integration to get your site up and running. However, we strongly recommend implementing a custom footer or other prominent show link. A custom implementation gives you complete design flexibility and control over the user experience, ensuring a seamless visual integration with your site.

To implement a custom Show Builder link, build your desired UI containing the link (footer, nav button, sticky bar, etc.). Then use GLOW's built-in subscription to dynamically toggle its visibility, ensuring it only appears when the user has items in their show:

// Example implementation toggling visibility of a custom footer link.
const customShowLinkFooter = document.querySelector('.my-custom-footer');

glow.subscribe.isShowPopulated({ listener: (isShowPopulated) => {
  // Assuming you use flex layout - update this code if needed.
  customShowLinkFooter.style.display = isShowPopulated ? 'flex' : 'none';
}});

Official Show Previews

If you sell pre-built shows, you can embed inline 3D show previews just like your product previews. To enable this, you'll need the show ID, which is found in your published show links. For example, if your show link is glfw.io/share/2ZH232T, the show ID is 2ZH232T.

Embed the show ID as the data-glow-show-id attribute in your button's HTML, then use the previewShow feature to make all show preview buttons interactive.

HTML
<button class="glow-preview-show-btn" data-glow-show-id="2ZH232T">
  3D Show Preview
</button>

JavaScript
glow.setupInteractions({
  previewShow: {
    buttonSelector: '.glow-preview-show-btn'
  }
});

Custom ID Extraction

Your website's HTML structure may differ from the standard examples, placing required attributes (e.g. data-glow-product-id) on a parent or sibling element instead of directly on the buttons. GLOW lets you easily define custom extraction logic for such cases.

Example: Extracting IDs from a Parent Element

Given this HTML structure:

HTML
<div class="button-wrapper" data-glow-brand-id="sample" data-glow-product-id="demo-500g">
  <button class="glow-preview-btn">3D Preview</button>
</div>

You can define the following extraction logic:

JavaScript
glow.setupInteractions({
  extractDataFromElement: (button) => ({
    brandId: button.parentElement.getAttribute('data-glow-brand-id'),
    productId: button.parentElement.getAttribute('data-glow-product-id')
  }),
  preview: {
    buttonSelector: '.glow-preview-btn'
  },
  // ...other features
});

This works with both preview and add-to-show buttons.

Extracting IDs for Show Previews

For Official Show Previews, use a similar pattern but define it separately under previewShow, as it uses showId:

Given this HTML structure:

HTML
<div class="button-wrapper" data-glow-show-id="2ZH232T">
  <button class="glow-preview-show-btn">3D Show Preview</button>
</div>

You can define the following extraction logic inside the previewShow object:

JavaScript
glow.setupInteractions({
  previewShow: {
    buttonSelector: '.glow-preview-show-btn',
    extractDataFromElement: (button) => ({
      showId: button.parentElement.getAttribute('data-glow-show-id')
    })
  }
});

This allows GLOW to support your existing HTML without additional markup changes.

Table of Contents​

Before You Start​

Step 1: Setting Up Product Identifiers for GLOW​

How GLOW Identifies Products​

How to Use IDs on Your Website​

Step 2: Load and Initialize the GLOW Library​

Step 3: Add Interactive Features​

Step 4: Embedding the Show Builder Application​

Create the Show Builder Page​

Load the Show Builder Application​

Final Checklist​

Promoting the 3D Show Builder​

Troubleshooting & Common Errors​

Feature Reference​

Watch Mode​

3D Product Previews​

Add-to-Show Buttons​

Floating Show Builder Link​

Official Show Previews​

Custom ID Extraction​

Table of Contents

Before You Start

Step 1: Setting Up Product Identifiers for GLOW

How GLOW Identifies Products

How to Use IDs on Your Website

Step 2: Load and Initialize the GLOW Library

Step 3: Add Interactive Features

Step 4: Embedding the Show Builder Application

Create the Show Builder Page

Load the Show Builder Application

Final Checklist

Promoting the 3D Show Builder

Troubleshooting & Common Errors

Feature Reference

Watch Mode

3D Product Previews

Add-to-Show Buttons

Floating Show Builder Link

Official Show Previews

Custom ID Extraction