Collapse Menu
Docs Home
Developer Tools
Contact Support

Get Started with Store Builder Library

Overview

Overview of the Store Builder Library and how to get started with it.

FastSpring's Store Builder Library (SBL) is a JavaScript library that advanced businesses can use to add ecommerce features to a website. For example, you can use SBL to create a complete, full-featured cart that blends with your website design. With the SBL, you can:

  • Display products created in your FastSpring Store directly on your website with localized prices and descriptions.
  • Use the library to apply coupons, add products to the cart, and populate consumer information to expedite the checkout process.
  • Use the library to provide consumers the ability to pay using a Popup Storefront.

Get Started

Using the library is similar to using Google Analytics scripts or integrating with Facebook's SDK. You must have basic HTML and JavaScript knowledge to get started. After it it is referenced and configured on your webpage, the library provides you with two ways of interacting with data:

  • "Simple" – Enable links on the page to add items to the cart, initiate checkout, apply coupon codes, and more. This approach is usually enough for scenarios like applying a coupon code before redirecting to checkout or displaying localized prices. See Accessing the Library and Data from HTML for additional information.
  • "Advanced" – Using callbacks provided by the library, get cart and order data to create a full-featured storefront on your website. You can display cart contents to consumers and utilize data to build a custom ecommerce experience. For more information, refer to Accessing the Library from Javascript.

Whichever way you choose, you need to start by referencing the library on your page and making sure that the data is loading successfully.

For interactive examples and implementation guidance we recommend exploring fastspringexamples.com and http://fastspring.github.io/playground/

Store Builder Library must be initialized with a specific Storefront. The Storefront specified in the data-storefront attribute of the SBL script is used when the consumer is ready to check out. Products associated with the Storefront are available in the data returned by the FastSpring backend to the Store Builder Library.

Use either a Web Storefront or a Popup Storefront with the Store Builder Library. The two types of Storefronts offer the same behavior and the same types of data via SBL. The only difference is what happens when the buyer initiates checkout.

For Popup Storefronts: If you plan to use a Popup Storefront, make sure to whitelist domains where the Popup Storefront will appear. All of your domains (including those you use for testing and development) must be whitelisted.
 
Additionally, we recommend that you deploy a security certificate and use the HTTPS: protocol for your website. Otherwise, most web browsers will not display a closed padlock icon, and some may display warning messages about non-secure pages. See Popup Storefronts and Browser Security Features for more information.

Select Products that will be Accessible via the SBL

If you would like to display dynamic, localized product pricing and descriptions to your consumers, you need to configure which products SBL can access. This scope of available products directly correlates to the Storefront specified when you initialize the library. To control this scope:

For Web Storefronts:

  1. Select Storefronts > Web Storefronts.
  2. For the Web Storefront you have chosen to use with the library, click Homepage. The Homepage Products dialog appears.

If you use a Web Storefront, keep in mind that this process also controls which items appear on the Homepage of the Storefront. For more information, see Choosing Products to be Displayed on the Storefront’s Homepage. If you plan to send some consumers to the homepage of a Web Storefront separately from your SBL, create a separate Web Storefront for use with the library. 

For Popup Storefronts

  1. Select Storefronts > Popup Storefronts.
  2. For the Popup Storefront you have chosen to use with the library, click Products. The Homepage Products dialog appears.

The Popup Storefront does not include a Homepage or product catalog. However, adding products via the Popup Storefront’s Homepage Products dialog makes them available in the library’s data. This lets you reference the products when accessing the library from HTML, and while using JavaScript.
 
Adding products to the Popup Storefront is only necessary if you want to display product attributes (price, display name, icon) on your SBL page. You can initiate checkout for any product ID in the Store, regardless of whether or not you have added it via the Popup Storefront’s Homepage products dialog.

Homepage Products Dialog

In the Main Products field, begin typing the name of the first product you want to add. Repeat this process to add any additional products that you want to make available to the library. 

Initialize the Library

After choosing the Storefront and selecting available products, you can insert the library into each page where you want to use its features. For interactive examples, see FastSpring Examples.

Get the Latest Library Code

Navigate to the Storefront of your choice, then:
  • For Web Storefronts, click the Links command. The code in the Advanced Links section of the resulting dialog references the Storefront and the latest version of the library.
  • For Popup Storefronts, click Place on your website. The code in the resulting dialog references the Storefront and the latest version of the library.
We recommend keeping your links to the SBL updated with the latest library URL to take advantage of the latest features and improvements.

Third-Party tools that attempt to compress, concatenate, or defer JavaScript loading interfere with initializing the SBL. For example, the Rocketscript tool from Cloudflare may modify your script that loads the SBL like:
<script id='fsc-api' data-rocketsrc="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.8.3/fastspring-builder.min.js">.
This likely will not work since the Store Builder Library does not support data-rocketsrc. To ensure the Store Builder Library loads successfully, avoid using these tools on pages that load the library.

Use Advanced Features

The code provided via the FastSpring App is limited to a simple reference. To use advanced features, provide additional data and register callbacks:

Store Builder Library Code Example

<script
  	id="fsc-api"
	  src="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.8.3/fastspring-builder.min.js"" type="text/javascript" 
  	  data-storefront="vendor.test.onfastspring.com"
	  data-data-callback="dataCallbackFunction"
	  data-error-callback="errorCallback"		
	  data-before-requests-callback="beforeRequestsCallbackFunction"
	  data-after-requests-callback="afterRequestsCallbackFunction"            
	  data-before-markup-callback="beforeMarkupCallbackFunction"
	  data-after-markup-callback="afterMarkupCallbackFunction"        
	  data-decorate-callback="decorateURLFunction"
	  data-popup-event-received="popupEventReceived"
	  data-popup-webhook-received="popupWebhookReceived"
	  data-popup-closed="onPopupClose"		
	  data-access-key=".. access key .."        
	  data-debug="true"    
	  data-continuous="true">
</script>

Full Code Reference

If you are providing callback functions to be called by the library, the functions must exist on the page when the library is loaded. Make sure to include the function (or the JavaScript file that contains the function) in your webpage in a place that will be loaded before the SBL calls are made.

  • id – Required, do not change value, must be "fsc-api".
  • src – Required, will be changed with each version of the FastSpring JavaScript API
  • data-storefront – Required, the Storefront that the API initializes. Use the Storefront's usual Domain URL without "https://"". For example, "vendor.test.onfastspring.com" or "vendor.test.onfastspring.com/holiday". This Storefront will be used when redirecting the consumer to checkout. You can use both Test and Live Storefronts here. Test Storefronts might not respond as quickly as Live Storefronts.
  • data-data-callback – A JavaScript function you should provide, which will be invoked when new JSON ("order object") is obtained from the server. This function must accept one parameter: an object. See more information Access the Library from Javascript for more information on returned data structure.
  • data-error-callback – A JavaScript function you should provide, which will be invoked when an error is received from the backend. This function must accept two parameters: an error code and an error string.
    • Error callback function example:
      function errorCallback (code, string) {
            console.log("Error: ", code, string);
      }
  • data-validation-callback – An optional JavaScript function, which must accept a JSON object consisting of an array with field validation results. Using the validation callback makes it easier to display user-friendly field validation error messages. See Accessing the Library from JavaScript for more information regarding the returned data structure.
  • data-before-requests-callback and data-after-requests-callback - Two JavaScript functions you may provide, which will be called before and after making any network requests. No parameters are passed to these functions.
  • data-before-markup-callback and data-after-markup-callback - Two JavaScript functions you may provide, which will be called before and after markup is performed. No parameters are passed to these functions.
  • data-decorate-callback - A JavaScript function you may provide, which will be invoked before redirecting to checkout to obtain Google Analytics linker "decorations." This function must accept a URL (string) as a parameter and return the decorated URL as a string. You must use this function if you are using Google Analytics for tracking, to avoid gaps in tracking your users.
    • Decoration callback example:
          function decorateURL(url) {
           var linkerParam = null;
         if ( ga && typeof ga === 'function') {
            ga(function()
            var trackers = ga.getAll()
            linkerParam = trackers[0].get('linkerParam');
            });
         }
        return (linkerParam ? url + '?' + linkerParam : url);
      }
  • data-popup-webhook-received – A JavaScript function you may provide, which will be invoked when the browser.order.completed browser script is received from the Popup Storefront. This function must accept one parameter: a JSON object. To set up webhooks, log in to the FastSpring App and navigate to Integrations > Webhooks. At least one event always fires following a successful order; the event contains basic order information. Refer to Webhooks > Browser Scripts for more information about the data structure.
  • data-popup-event-received – A JavaScript function you may provide, which will be invoked when an analytics event is received from the popup checkout process. This function must accept one parameter: a JSON object. See Google Universal Analytics for all event types our checkout process generates. Those events are intended for use with Google Analytics on your page. 
  • data-popup-closed – A JavaScript function you may provide, which will be invoked when the consumer closes the Popup Storefront. The function must accept a JSON object that contains the internal FastSpring order ID (key: id) and a consumer-facing order reference (key: reference). The library only passes the order id upon successful order completion. If the consumer closes the Popup Storefront before the order is completed, the library passes "null" instead.
    popup closed: Object {id: "IGcavRiVQm-Fd0sAtMoPUg", reference: "YES200310-8786-75309"}
    • For orders that use delayed payment methods, such as wire transfer orders, the JSON object does not contain the order reference. In such cases, it does still have the Order ID. 
    • Do not initiate redirect or a navigation page change after invoking the checkout but before receiving the "data-popup-closed" event. This might result in interruption of the checkout process. For suggested handling of the order completion in Popup Storefronts, please refer to Validating Popup Storefront Orders.
  • data-access-key – Required for making requests with a secure payload. Please refer to Passing Sensitive Data with Secure Requests for more information.
  • data-continuous – The default is "false". When set to "true", the library remembers a visitor in the browser (products currently in the cart, applied discounts, and other session data). It keeps that data across pages of a single domain for 24 hours. This method is useful if the visitor flow may be across multiple pages, and you want to display the correct pricing, including discounts, across all pages of the website. Continuous data uses JavaScript's local storage feature in the visitor's browser, so visitors do not need to have cookies enabled.
  • data-debug – The default is "false". When set to "true", the library provides extensive logging and other information to the browser console. 

Try FastSpring

Get a free account and see why FastSpring is the ecommerce partner of choice for software providers around the world. Try our full-service ecommerce solution today to unlock revenue growth for your online company.