Introduction

The BigCommerce Scripts API can be used to inject a script into a store’s template files. Some use cases:

  • Insert tracking codes
  • Storefront single-click applications
  • Live chat, support plugins
  • Theme extension or connector apps

Script Manager API Partner Guidelines

With the Script Manager API, your Apps now have the ability to insert scripts into a user’s storefront without requiring the user to manually paste a snippet of code into their control panel. You can freely update these scripts while your App is installed, and, if desired, automatically remove scripts if your App is uninstalled.

For Apps being installed on our latest theme engine (Stencil), this process is relatively straightforward. However, if your App is already live, you may have already asked merchants to paste a code snippet in one of these two sections in the control panel:

  • Footer Scripts
  • Web Analytics

Also, since our older (Blueprint-based) themes do not support the Script Manager API, you’ll still need some way of providing users of older themes the documentation they need, without burdening users of newer themes with additional, unnecessary steps.

To help you transition to the Script Manager API, we’ve provided some recommended strategies to deal with these different situations.

Stencil vs Blueprint

As mentioned above, BigCommerce supports two theme engines: Stencil and Blueprint. Stencil is our latest technology, and all new stores only have access to Stencil themes. However, older stores may still be using our legacy theme engine, Blueprint, which does not have the ability to render scripts inserted through the Script Manager API.

Because of this, you’ll need to check whether a user is running Stencil to determine if their store supports the Script Manager API. To do this, use the Get Store Information API endpoint and check the stencil_enabled flag. (requires store_v2_information_read_only scope).


Prerequisites

To better understand the content of this document, you should be familiar with the app installation procedure, which is outlined here: App Installation


Upgrades and Installation

Installing An App on Stencil

For Apps being installed on Stencil stores, we recommend inserting your scripts immediately after receiving the POST response during the Auth Callback flow. Add your scripts using the Create Script endpoint of the Script Manager API.

We highly recommend leaving the auto_uninstall flag set to true, so that your App will properly clean itself up when uninstalled. More information about this flag can be found here.

Upgrading Existing Apps on Stencil

If your App has already been released, you may have existing users with pasted-in code somewhere in their control panel. There are a few possible ways to deal with this situation.

1.) Do nothing

If you don’t need to upgrade existing merchants to the Script Manager API, it’s perfectly fine to leave them as-is. You’ll need to maintain documentation for the manual uninstallation process so that merchants with older installations know what to clean up, and you won’t be able to automatically update or add scripts for these users.

2.) Prompt merchants to upgrade

If you want your merchants to gradually update to the new Script Manager over time, you can prompt them to do so on your App’s landing page. You’ll need to keep track of which of your merchants are not using the Script Manager yet to know whether you need to display this prompt. Also, make sure to check that they are running Stencil (via the Get Store Information endpoint) before prompting them to upgrade.

Once a user decides to upgrade, you can walk them through removing the old pasted-in code in their control panel, and then, once the merchant clicks a button, install your scripts through the Script Manager API.

3.) Silently upgrade to the Script Manager API

Finally, if it’s possible for your old, pasted-in scripts to live alongside the new Script Manager API scripts, you may be able to upgrade to using the Script Manager API without any user intervention being required. Whether or not this is possible will vary depending on the implementation of your App.

While your merchants will be loading more data on their storefront pages than necessary, this method will allow you to transition to using the Script Manager API for all of your installations immediately. Keep in mind you’ll still need to document the manual uninstallation process for existing installations.

Installing Apps on Blueprint Stores

As mentioned, the Blueprint theme engine does not support the Script Manager API. Any scripts inserted through this API will not be rendered on any storefront pages. To prevent unpredictable behavior should a user change their theme, we highly recommend checking the Get Store Information endpoint for Stencil support prior to installing any scripts through the Script Manager API. Additionally, you’ll still want to show the old manual installation steps when a store does not support Stencil.

Existing Blueprint Installations

Existing blueprint installations won’t be affected, but remember that if you are prompting existing Stencil users to upgrade to the Script Manager, you’ll want to suppress this message for Blueprint users.


Fixing Missing Scripts

It’s possible that your App installation may find itself unexpectedly missing one or more scripts. Below are some possible causes of this issue.

1.) The Merchant Deleted Your Script

Merchants are given a warning when attempting to delete a script belonging to an App, but we do allow them to do so.

If you want to handle this situation gracefully, we recommend you check the Get Scripts endpoint on your App Detail Page (returned by the Load Callback URI to determine whether the expected scripts are present. If they are not, you can prompt the user to click a button to automatically repair their installation.

We ask that you request the user’s permission rather than doing this automatically, as they may have had a good reason for deleting the missing script.

2.) The Merchant’s Theme is Not Set Up Correctly

In order to render scripts, the theme templates must have the handlebars expressions {{head.scripts}} and {{footer.scripts}} in the pages where scripts should be rendered. If either of these is absent, scripts on that page with location set to head or footer (respectively) will not be rendered.

Of particular note, {{head.scripts}} was only recently added to the checkout and order confirmation pages in our Cornerstone theme, and widespread adoption of this standard outside of Cornerstone is still an ongoing process.

To ensure your App is compatible with as many themes as possible, we recommend footer over head for checkout, order_confirmation and all_pages visibilities.

3.) Scripts Are Not Rendering in the Checkout and Order Confirmation

In order to render scripts, the store must have BigCommerce’s Optimized one-page checkout enabled. This is the default checkout type for all new Stencil stores. Existing stores have to manually change the checkout type as detailed in this article.

Stencil themes from the marketplace support the Optimized One-Page Checkout. However, there could be instances where the merchant maintains their own private theme and the theme has not been updated to support the Optimized one-page checkout. In this case, the merchant is required to add the theme support, following the steps here.


Notes

  • If you are injecting scripts into the Checkout, you will need to update the scope to Checkout Content. Accounts can only be created by the store owner.
  • Merchants will be able to see the scripts installed on the store in the Control Panel. Within the native tag manager, merchant actions will be limited to viewing a script and deleting a script.
  • Scripts can be located in the header {{head.scripts}} or footer {{footer.scripts}}.
  • Scripts Manager is only for Stencil themes. Blueprint store users will still need to copy and paste in code.
  • The current visibility options are storefront, checkout, all_pages and order_confirmation.
  • Scripts injected via the Scripts API will not render when you are developing a theme locally via Stencil CLI.

Script Visibility Locations

Scope Visibility
all_pages Add Wishlist
Blog List
Blog Post
Brand Pages
All Brands Page
Cart
Category
Checkout
Checkout
Product Compare
Order Confirmation
Page
Contact Form
Product
Search
All Wishlist
Wish List
storefront Add Wishlist
Blog List
Blog Post
Brand Pages
All Brands Page
Cart
Category
Checkout
Checkout
Product Compare
Page
Contact Form
Product
Search
All Wishlist
Wish List
checkout Checkout
order_confirmation Order Confirmation

Scripts can not be injected to:

  • giftcertificates.php
  • sitemap.php
  • account.php
  • login.php
  • 404 pages

OAuth Scopes

  • Checkout Content
  • Content

For more details and a full list of available scopes, see Oauth Scopes.


Related Endpoints


Object Properties

object
uuid
string

The primary identifier.

format: uuid
name
string

The user-friendly name.

description
string

The user-friendly description.

html
string

An html string containing exactly one script tag. Only present if kind is script_tag

src
string

The src attribute of the script to load. Only present if kind is src.

auto_uninstall
boolean

It will enable automatic cleanup of the script when the single click app is uninstalled or OAuth token is revoked.

load_method
string

The load method to use for the script. Values are default, async, or defer. It determines how the script should be loaded into the page.

Allowed Values: default, async, defer
location
string

Where on the page to place the script. Values are head or footer.

Allowed Values: head, footer
visibility
string

Which set of pages the script should load on.

Please note that you need to have Checkout content scope to use all_pages and checkout.

  • The current visibility options are storefront, checkout, all_pages and order_confirmation.

    storefront: All pages that are not checkout or order_confirmation.

For a list of all locations visit Scripts Visibility.

Allowed Values: storefront, all_pages, checkout, order_confirmation
kind
string

What type of script this is.

src - a script tag will be generated with its src attribute set to the value of src; For scripts that use the src url. By providing a path to the script, we can optimize and serve the script tag automatically for you.

script_tag - The value of html will be injected directly onto the page. For scripts which include a raw HTML script_tag to be inserted into the page. The load_method must be default.

Allowed Values: src, script_tag
api_client_id
string

The client id of the API user that created this script, or blank if created by other means.

date_created
string

The date on which this object was initially created.

format: date-time
date_modified
string

The date on which this object was last updated.

format: date-time