Overview

Upfront.js provides components for developing applications that integrate with Upfront on merchant storefront websites.

Upfront.js provides HTML elements which applications can display and control in their user interface. All of our elements are HTML custom elements and can be used like normal DOM elements (event listeners, CSS, etc) in combination with Upfront specific attributes.

Compatibility

Upfront.js supports the following browser versions:

Browser	Version
Chrome	94+
Firefox	92+
Edge	94+
Safari	14+
iOS Safari	14+
Android Browser	93+

JavaScript must be enabled in the browser for Upfront.js to work. Upfront.js is able to be used within any modern Javascript framework. It can also be used independent of a framework as well.

Loading

Upfront.js is hosted on Upfront's servers and should be loaded with a script tag directly from our CDN:

<body>
  <script src="https://assets.knowupfront.com/storage/v1/object/public/sdk/upfront.js"></script>
</body>

Note that Upfront.js should be loaded synchronously (should not set a defer or async attribute on the script tag). To avoid blocking critical loading of the document, we recommend including the script tag near the end of the body element.

Async loading

Upfront has an NPM package, which provides an ES module for loading Upfront.js async. This is an alternative to using a script tag. If you are using Typescript, this is usually the desired way to load Upfront.js.

Install:

npm i @knowupfront/upfrontjs

Usage:

import { loadUpfrontjs } from '@knowupfront/upfrontjs';

const upfrontjs = await loadUpfrontjs();
upfrontjs.init("<merchant public key value>", {
    // Optional configuration settings
});

Initialization

The first step of using Upfront.js is initializing the library on your website. When Upfront.js executes, a single object named upfrontjs is placed in the global namespace. The SDK must be initialized for a specific merchant by calling the upfrontjs.init(). This only needs to be done once during the lifecycle of the application.

<body>
  <script src="https://assets.knowupfront.com/storage/v1/object/public/sdk/upfront.js"></script>
  <script>
    upfrontjs.init("<merchant public key value>");
  </script>
</body>

This method accepts one parameter, publicKey. This parameter is required and is the merchants public API key.

The return value of this method is a promise resolved to an instance of an Upfront handler. This handler contains an interface for all SDK functions that are available post-initialization. In the application, a reference to this handler object should be saved.

upfrontjs.init("<merchant public key value>")
.then(function (upfrontHandle) {
  // Save a reference to the handle object here
})
.catch(function (error) {
  // init failed
});