# JavaScript API

# When to Use

In some cases, the out-of-the-box reference implementation may not be a good fit for the host site requirements. While a lot can be by tweaking and extending the reference code, some requirements may require developers to tap into the JavaScript API directly. The Customizer's JavaScript API provides many classes and helpers that can be used to enhance the app functionality, or be used as building blocks to create totally new experiences.

# Integrating the API

Main API URL:

https://api.customizer.drivecommerce.com/api/v2/runtime/client?type=production

Load the Javascript API using one of the following two methods.

TIP

The reference implementation already loads the API automatically.

# Dynamic Script Loading

const clientRoot = 'https://api.customizer.drivecommerce.com/api/v2/runtime/client?type=production';

(function ClientLoader(url, onload) {
    const script = document.createElement('script');
    script.type = 'text/javascript';
    script.onload = onload;
    script.src = url;
    document.head.appendChild(script);
}(clientRoot, () => {
    // Customizer is now ready for use.
    ...
}));

Dynamic loading is a preferred method of integrating Customizer JavaScript API, as it does not block page functionality while the script is loading and being initialized.

WARNING

Dynamic loading methods using jQuery getScript function, deferred, or async script tags are not supported.

# Static Script Loading

Add at the end of your body tag

<script type="application/javascript" src="https://api.customizer.drivecommerce.com/api/v2/runtime/client?type=production"></script>

Page initialization code

// For example, use jQuery $.ready function to wait until DOM can be safely manipulated.
$(function () {
    // Customizer is now ready for use.
    ...
});

The simplest method of integration comes at the cost of blocking page functionality while the script is loading, which may reduce overall page performance.

# API Objects

The API creates a DriveCustomizer namespace in the global scope that provides following classes:

Class	Purpose
Controller	The main class that implements communication with the Customizer backend and provides product state management and manipulation.
ImageView	Implements 2D stacked-image product rendering approach.
UndoStack	A helper class that implements undo and reset functionality, if required by the UI.

# Controller Class

Controller is a primary class in the Customizer JavaScript API. It implements communication protocol with the Customizer backend to retrieve product blueprints and save customized recipes, provides product state management and ensures configured product validity, and contains a number of utilities that may be helpful to create rich and robust customization UIs.

# Authorization

Controller instances require an API key to communicate with the Customizer backend. New API keys can be created as needed in the Account section of the administration website.

# Creating Controller Instances

const controller = new window.DriveCustomizer.Controller({
    product: 'WATCH360',
});

controller.load();

To begin working with the controller object, create an instance using the DriveCustomizer.Controller constructor and provide initialization parameters:

Option
apiKey	The API key that authorized the API usage.
product	The style code of a product to be loaded.
products	The array of style codes to be loaded.
blueprint	Instead of providing product style codes allows specifying the blueprint URL directly.
currency	If using Customizers price calculations provides the current currency ISO code.

# Load Product Information

controller.load();

Kick-off the customization process by invoking the load method.

← Widgets API Reference →