@maxdigital/sdk.js

Installation

The following embed code can be used on your website:

<script>
(function(m,a,x,s,d,k){m.MaxApps=m.MaxApps||{};d=a.createElement(x);d.async=1;
d.src=s;k=a.getElementsByTagName(x)[0];k.parentNode.insertBefore(d,k)})
(window,document,'script','https://maxapps.io/sdk.js');
</script>

Configuration

If configuration is provided on page load (most common), the embed code will automatically boot and load all configured plugins. At minimum, a list of widgets to use must be supplied. A valid dealer ID is optional.

<script>
(function(m,a,x,s,d,k){m.MaxApps=m.MaxApps||{};d=a.createElement(x);d.async=1;
d.src=s;k=a.getElementsByTagName(x)[0];k.parentNode.insertBefore(d,k)})
(window,document,'script','https://maxapps.io/sdk.js');
</script>
<script>
  MaxApps.dealerId = '0C1B63CA-F1A7-E011-BBB1-001B219B7C2C'
  MaxApps.use = ['tradeInTool']
</script>

For more advanced setups, such as use on a SPA, the widget may be booted manually with the necessary configuration. This can be done with the standard embed code from above or by importing as an NPM module to be used in your build system:

import maxapps from '@maxdigital/sdk.js'

maxapps.boot('0C1B63CA-F1A7-E011-BBB1-001B219B7C2C', {
  use: ['tradeInTool']
  tradeInTool: {
    selector: 'custom-selector'
  }
})

Writing Plugins

Non-core plugin exist outside of this project as standalone apps. Plugins can extend core functionality, require other plugins, or exist as an entirely standalone application.

Naming

A unique name should be used for each plugin. This key is used to load the plugin, namespace it within the SDK, and provide a unique configuration key. Plugin names should always be lowerCamelCase.

Creating

The entry point for the plugin will be executed when the SDK is booted. If a module bundler such as Webpack is not used, take care not to pollute the global namespace since the SDK may be used on a variety of different sites with existing JS libraries.

Each plugin should register itself with an install function upon loading. This will make the module active in the SDK. For most simple use-cases, the following function can be used in the entry point:

window.maxsdk.plugin('tradeInTool', function (config, require) {

  // `config` includes an object if a configuration key has been provided by the
  // user when registering the SDK. It should be treated as optional.

  // `require` allows the plugin to declare a dependency on other plugins or
  // load external fonts or stylesheets. If you are using a bundler such as
  // webpack it is better to use this for any local dependencies.

});

Remember, the name you use when registering the plugin should also match the filename of the entry point. This will also be used for namespacing the module, in the above example maxsdk.app.tradeInTool will contain the install function and any user provided configuration at the tradeInTool key will be included in the first parameter.

For more advanced use cases, such as when a plugin is meant to be used as a dependency, or if it just needs to expose functions after installation, an object may be provided instead:

window.maxsdk.plugin('tradeInTool', {
  get vin() {
    // Functions, properties, etc. are all exposed at `maxsdk.app.tradeInTool`
    // Another plugin can call this via `maxsdk.app.tradeInTool.vin`
  },
  install: function (config, require) {
    // This is invoked same as the above example!
  }
};

Deploying

All plugins should be published to the MaxApps SDK endpoint, under the /apps directory. When deployed, the filename of the entry point should match the name of the plugin along with a .latest.js suffix. This will be extended in the future with the ability to lock plugins to a semantic version number or tag. Additional files required (ex. module splitting, stylesheets, etc.) should either use the same plugin name prefix or be written to a folder matching the plugin name inside of /apps. It is recommended that all lazy-loaded requirements include a hash for caching purposes.