Getting Started with Store Builder Library

Last modified October 17, 2017

Choosing a Storefront

Store Builder Library must be "initialized" with a specific Storefront. This Storefront will be used when you are ready to "checkout" a customer and products "associated" with the Storefront will be available in the data returned by 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. There is no difference in behavior of those Storefronts in regards to the Store Builder Library and available data. 

Note

If you are planning to use a Popup Storefront, you will need to get in touch with FastSpring support to "whitelist" domains where the Popup Storefront will be shown. All of your domains (including those you will 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 which will be accessible with the Library

If you would like to display localized product pricing and descriptions to your customers you need to explicitly choose products which will be delivered to your page. To do this:

  • Log in to the FastSpring Dashboard
  • Navigate to the Storefront you have chosen to use with the Library
  • For Web storefronts – click to setup Homepage Products
  • For Popup storefronts – click to setup Products

Products selected in those corresponding areas will be available in the dataset and can be used when accessing Library from HTML using Markup and accessing Library from Javascript.

Initializing the Library

After choosing the Storefront and selecting available products you can insert the Library to all pages where it's features will be used.

Tutorial Video

Check out our tutorial video on adding a Popup Storefront to your website, which includes a functional demonstration of initializing the Store Builder Library:   How to Add a Popup Storefront to Your Website.

To get the latest library code, navigate to the Storefront of your choice and click "Place storefront on your website". The code will reference the selected storefront and the latest version of the Library.

Note

We recommend that you keep your links to the Store Builder Library updated with the latest / current URL, in order 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.7.4/fastspring-builder.min.js"> . This may not work because data-rocketsrc is not supported by Store Builder Library at this time. To ensure the Store Builder Library can load successfully, we recommend that you avoid using these types of tools on pages that load the library.


The code provided will be limited to a simple reference, but to use advanced features you will need to provide additional data and register callbacks:

Store Builder Library code example
<script
  	id="fsc-api"
	  src="https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.7.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 1 parameter, an object. See more information on returned data structure in Accessing 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 2 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-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 for the purpose of obtaining 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 webhook event is received from the Popup store. This function must accept 1 parameter, an object. To setup webhooks, login to Dashboard and navigate to Integrations > Webhooks. At least one event will always fire on successful order containing basic order information. Refer to Webhooks > Browser Script Examples for more information about 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 1 parameter, an object. See Google Universal Analytics docs for all event types our checkout process generates. Those events are intended to be used with Google Analytics on your page. 
  • data-popup-closed – A JavaScript function you may provide, which will be invoked when popup is closed. The function must accept an object which will contain the internal FastSpring order ID (key: id) and a customer-facing order reference (key: reference). The order id will only be passed upon successful order completion. If the popup is closed before the order is completed, "null" will be passed.

    Example of the data-popup-closed object
    popup closed: Object {id: "cbhpinwOS52LKQ5SMoU812", reference: "FUR161216-8786-75309"}
    Do not initiate redirect, navigation page change after you directed your customer to checkout and before you received "data-popup-closed" event. This might result in interruption of the checkout process. For suggested handling of the order completion in popup stores please refer to Validating Popup Storefront Orders.
  • data-access-key – Required for making requests with the 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 cart, applied discounts, etc) and keeps that data across pages of a single domain for 24 hours. This 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 it is not necessary for visitors 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. 
If you are providing callback functions to be called by the FastSpring API, the functions must exist on the page when the Library is loaded. Make sure the function (or the inclusion of the JavaScript file that contains the function) is located in your webpage in a place that will be loaded before the API calls are made.


https://d1f8f9xcsvx3ha.cloudfront.net/sbl/0.7.4/fastspring-builder.min.js