Installing the Widget on BigCommerce

Overview

This guide will walk you through installing our JavaScript widget on your BigCommerce store. BigCommerce provides flexible options for adding custom code to your e-commerce site.

Method 1: Using Script Manager (Recommended)

Script Manager is BigCommerce's built-in tool for adding scripts site-wide or to specific pages.

Step 1: Access Script Manager

1. Log in to your BigCommerce admin panel
2. Navigate to Storefront → Script Manager
3. Click Create a Script button

Step 2: Configure Script Settings

1. Script Name: Enter a name (e.g., "My Widget Script")
2. Description: Optional description for your reference
3. Location on page: Select Footer
4. Select pages where script will be added: Choose one of:
   • All Pages (recommended for site-wide installation)
   • Storefront pages
   • Checkout pages
   • Order confirmation page
   • Specific page types

Step 3: Script Category

Select Essential or Analytics depending on your widget's purpose.

Step 4: Script Type

Select Script

Step 5: Add Your Widget Code

In the script contents box, paste your widget script:

<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY'
  });
</script>

Replace YOUR_API_KEY with your actual API key from your dashboard.

Step 6: Save

1. Click Save button
2. Your widget is now active on your store!

Method 2: Theme File Editing (Advanced)

For more control, you can edit your theme files directly.

Step 1: Access Theme Files

1. Go to Storefront → Themes
2. Find your active theme
3. Click Advanced → Edit Theme Files

Step 2: Edit base.html or footer.html

1. Navigate to templates → layout
2. Click on base.html (or footer.html if available)
3. Find the closing </body> tag (usually near the bottom)

Step 3: Add Your Widget Script

Paste your widget script just before the </body> tag:

    <!-- Your Widget Script -->
    <script src="https://your-domain.com/widget.js"></script>
    <script>
      YourWidget.init({
        apiKey: 'YOUR_API_KEY'
      });
    </script>
</body>

Replace YOUR_API_KEY with your actual API key.

Step 4: Save and Apply

1. Click Save (or Save & Apply if available)
2. If prompted, apply changes to your live store

Warning: Changes to theme files will be lost if you switch themes or update your theme. Use Method 1 (Script Manager) for a more permanent solution.

Method 3: Page Builder Widget

If using BigCommerce's Page Builder:

Step 1: Edit Page

1. Go to Storefront → Web Pages
2. Select the page you want to edit
3. Click Edit in Page Builder

Step 2: Add HTML Widget

1. Click where you want to add the widget
2. Search for or select HTML widget
3. Drag it onto your page

Step 3: Add Your Code

1. Click on the HTML widget
2. In the settings panel, paste your widget script:

<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY'
  });
</script>

3. Replace YOUR_API_KEY with your actual API key
4. Click Save or outside the widget

Step 4: Publish

1. Click Publish to make the page live

Note: This method only adds the widget to that specific page.

Installing on Specific Page Types

On Product Pages Only

Using Script Manager:

1. In step 2, select Storefront pages → Product pages
2. Follow the remaining steps

On Cart Page Only

Using Script Manager:

1. In step 2, select Storefront pages → Cart page
2. Follow the remaining steps

On Checkout Pages

Using Script Manager:

1. In step 2, select Checkout pages
2. Follow the remaining steps

Note: For security, some checkout page features may be limited.

On Order Confirmation Page

Using Script Manager:

1. In step 2, select Order confirmation page
2. Follow the remaining steps

Installing with Stencil Themes

For stores using Stencil themes:

Using Front Matter

Add to specific template pages by editing the page's front matter:

1. Edit the template file (e.g., product.html)
2. Add to the front matter section:

{{#partial "page"}}
<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY'
  });
</script>
{{/partial}}

Using Stencil CLI

If developing locally:

1. Edit your theme files
2. Use stencil push to upload changes
3. Apply the updated theme

Troubleshooting

Widget Not Appearing

1. Check Script Manager:

   • Go to Storefront → Script Manager
   • Verify your script is Active (green toggle)
   • Check page selection settings

2. Clear cache:

   • BigCommerce uses CDN caching
   • Wait 5-10 minutes for changes to propagate
   • Use Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
   • Try incognito/private browsing

3. Verify consent manager:

   • If you have a cookie consent manager, ensure scripts are allowed
   • Check if your widget needs consent approval

4. Check browser console:

   • Right-click → Inspect → Console tab
   • Look for any error messages
   • Share errors with our support team

5. Verify API key:

   • Ensure you replaced YOUR_API_KEY with your actual key
   • Check for extra spaces or estimates
   • Confirm key is correct in your dashboard

Script Manager Script Not Running

• Check the Script Category - try changing between Essential/Analytics
• Verify Location on page is set to Footer
• Ensure the script is enabled (toggle should be green)
• Check page selection matches where you're testing

Widget Appears Multiple Times

• You may have added the script in multiple places:
  • Script Manager
  • Theme files
  • Page Builder widgets
• Remove duplicate installations

Widget Not Working on Checkout

• Checkout pages have security restrictions
• Some custom scripts may be limited
• Contact BigCommerce support to verify if your use case is allowed
• Consider adding to order confirmation page instead

Best Practices

1. Use Script Manager (Method 1) for most cases - it's the easiest and most maintainable
2. Select "Footer" placement for better page load performance
3. Test in multiple browsers and devices
4. Keep your API key secure - never expose it publicly
5. Document your installation - note which method you used

BigCommerce Plan Compatibility

All BigCommerce plans support custom scripts:

Important Notes

⚠️ Theme Updates:

• Scripts in Script Manager persist through theme updates
• Scripts in theme files will be lost when updating/changing themes
• Always use Script Manager when possible

⚠️ CDN Caching:

• BigCommerce uses CDN caching
• Changes may take 5-10 minutes to appear
• Use incognito mode for immediate testing

⚠️ Stencil vs. Blueprint:

• Most modern stores use Stencil (recommended)
• Blueprint is legacy and being phased out
• This guide focuses on Stencil themes

Advanced Configuration

Loading Widget Based on Customer Login Status

<script>
  {{#if customer}}
    // Customer is logged in
    var script = document.createElement('script');
    script.src = 'https://your-domain.com/widget.js';
    script.onload = function() {
      YourWidget.init({
        apiKey: 'YOUR_API_KEY',
        customerId: '{{customer.id}}'
      });
    };
    document.body.appendChild(script);
  {{/if}}
</script>

Passing Product Data to Widget

On product pages:

{{#partial "page"}}
<script src="https://your-domain.com/widget.js"></script>
<script>
  YourWidget.init({
    apiKey: 'YOUR_API_KEY',
    productId: '{{product.id}}',
    productName: '{{product.title}}',
    productPrice: '{{product.price.with_tax.value}}'
  });
</script>
{{/partial}}

Testing Your Installation

Verification Steps

1. Visit your storefront in a new browser tab
2. Right-click and select Inspect or Inspect Element
3. Go to Console tab
4. Look for any errors related to your widget
5. Go to Network tab
6. Refresh the page
7. Search for your widget script URL
8. It should load with status 200 OK

Multi-Storefront Support

If you have multiple storefronts:

1. Each storefront can have its own Script Manager scripts
2. Add the widget to each storefront individually
3. Or add to theme files that are shared across storefronts

Need Help?

If you encounter any issues:

• Check our FAQ at [your-support-url]
• Contact our support at [your-support-email]
• Include your BigCommerce store URL
• Mention your theme name if known
• Take screenshots of Script Manager settings and any errors

You can also contact BigCommerce Support:

• BigCommerce Help Center
• They can help with theme file editing and script issues

Removing the Widget

To remove the widget from your BigCommerce store:

If using Script Manager:

1. Go to Storefront → Script Manager
2. Find your widget script
3. Click the ... (three dots) menu
4. Select Delete
5. Confirm deletion

If using Theme Files:

1. Go to Storefront → Themes → Advanced → Edit Theme Files
2. Navigate to the file where you added the script (e.g., base.html)
3. Find and delete the widget script
4. Click Save

If using Page Builder:

1. Edit the page containing the HTML widget
2. Click on the HTML widget
3. Delete the widget code or delete the entire widget
4. Click Publish

Migration & Backup

• Always backup your theme before making changes
• Use the Download Theme File option before editing
• Consider creating a test store for trying new scripts
• Keep a copy of your widget code in a safe place

Quick Reference

Easiest Method: Script Manager (Method 1) Most Flexible: Theme File Editing (Method 2) Page-Specific: Page Builder (Method 3)

Remember: Script Manager is recommended for most users!