Collapse Menu
Docs Home
Extensibility Options
Contact Support

Getting Started with Store Builder Library

Overview

This article covers the basics of Store Builder Library.

This article covers the basics of Store Builder Library (SBL).

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 customer 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.

You can use either a Web Storefront or a Popup Storefront with the Store Builder Library, depending on the preferred checkout experience. 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.

 Note

If you are planning to use a Popup Storefront, you must "whitelist" domains where the Popup Storefront is to appear. All of your domains (including those you use for testing and development) need to be whitelisted.

 Tip

When using a Popup Storefront, 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. For more information, please see Popup Storefronts and Browser Security Features.

 

Selecting Products That Will Be Accessible with the Library

If you would like to display dynamic, localized product pricing and descriptions to your customers, 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.

 

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.

 

Using the Homepage Products Dialog

In the Main Products field, begin typing the name of the first product you want to add. As you type each character, the FastSpring App automatically filters a list of matching products dynamically. To select the product from the list, you can use the arrow keys and press Enter/Return or just click the desired product. Then, repeat this process to add any additional products that you want to make available to the library. If you make a mistake, click the red Remove command to the left of the product that you do not want to include in the Storefront.

 Note about Web Storefronts

If you are using a Web Storefront, keep in mind that this process also controls which items appear on the Homepage of the Storefront. For more information, please see Choosing Products to be Displayed on the Storefront's Homepage. If you plan to send some customers to the Homepage of a Web Storefront separately from your Store Builder Library implementation, you can create a separate Web Storefront for use with the library, if need be.

 Note about Popup Storefronts

The Popup Storefront does not include a Homepage or product catalog. However, adding products via a 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 using markup and accessing the library using JavaScript. Adding products to the Popup Storefront is only necessary if you want to display product attributes (such as price, display name, or 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.

 

Initializing the Library

After choosing the Storefront and selecting available products, you can insert the library into all pages where you want to use its features.

 Live Interactive Examples

Check out our interactive, hands-on examples at https://www.fastspringexamples.com.

 

To 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.

 Note

It is a good idea to keep your links to the Store Builder Library updated with the latest/current library URL, to take advantage of the latest features and improvements.

 Note

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

The code provided via the FastSpring App is limited to a simple reference. To use advanced features, you can 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

  • 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 customer 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 on returned data structure in Accessing the Library from Javascript.
  • 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. See the example callback function below. 
    Error callback function example
    function errorCallback (code, string) {
      	console.log("Error: ", code, string);
    }
    
  • data-validation-callback – An optional JavaScript function you can provide, 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 more information on the returned data structure in Accessing the Library from JavaScript.
  • 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 customer closes the Popup Storefront. The function must accept a JSON object that contains the internal FastSpring order ID (key: id) and a customer-facing order reference (key: reference). The library only passes the order id upon successful order completion. If the customer closes the Popup Storefront before the order is completed, the library passes "null" instead.

     Note

    For orders that use certain types of 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.
     
    Example of the data-popup-closed object
    	popup closed: Object {id: "IGcavRiVQm-Fd0sAtMoPUg", reference: "YES200310-8786-75309"}
    	
     

     Caution

    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. 

 Tip

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.

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.