Using Appmixer SDK

The Appmixer JavaScript SDK allows you to embed any of the UI widgets of Appmixer into your own web products. You can also take advantage of the SDK methods to communicate with the Appmixer engine REST API.

Open the Appmixer SDK demo

Start with opening the Appmixer SDK demo in your browser:

$ cd appmixer/frontend/appmixer/
$ open demo.html

Or you can download the necessary files from the Appmixer front-end:

# Download the Appmixer SDK:
$ wget http://localhost:8080/appmixer/appmixer.js
# Download the demo page:
$ wget http://localhost:8080/appmixer/demo.html
# Download the example theme object:
$ wget http://localhost:8080/appmixer/theme.js
$ open demo.html

Notice that this won't work yet since we haven't configured basic required variables. First we need to edit the demo HTML file to add base URL of our Appmixer engine REST API and our user credentials. Open the frontend/appmixer/demo.html file in your editor and find the following section:

    <script>
        var BASE_URL = '<your-base-url>';
        var USERNAME = '<your-username>';
        var PASSWORD = '<your-password>';

Replace <your-base-url> with http://localhost:2200 and <your-username> and <your-password> with the user credentials that you used in the Getting Started guide to sign-up your first user. Now you can open the demo.html file in your browser. You should see something like this:

Appmixer SDK Demo

The demo shows a plain HTML page that embeds the Appmixer UI widgets via the Appmixer JS SDK. Try to switch to different widgets using the select control at the top:

Insights page in Appmixer SDK Demo

Study the source code of the demo.html file to understand how the Appmixer SDK can be used to embed Appmixer UI into your own page. As you can see, we start by authenticating the user:

appmixer.api.authenticateUser(USERNAME, PASSWORD).then((auth) => {
    appmixer.set('accessToken', { token: auth.token, userId: auth.user.id });
    start();
});

Then we initialize the Appmixer UI widgets passing a reference to a <div> container element they will render in:

<div id="your-flow-manager"></div>

var flowManager = appmixer.ui.FlowManager({ el: '#your-flow-manager' });

Once our widgets are initialized, we can just call open() and close() methods to render the widgets inside their container or close them:

flowManager.open();

And react on events the UI widgets provide. For example, if the user clicks a flow inside the flow manager, the flow manager widget triggers the "flow:open" event which we can react on to open the designer for that flow:

flowManager.on('flow:open', (flowId) => {
    designer.set('flowId', flowId);
    flowManager.close();                        
    designer.open();
});

To revoke the authenticated user access, unset the access token:

appmixer.set('accessToken', null);

To learn more about the Appmixer JavaScript SDK, please visit the Appmixer SDK section.

Webpack usage

We recommend to include Appmixer SDK as a script (the same way it is used in demo.html) whenever possible. This is because Appmixer SDK is too big to be processed as a module in a bundler like Webpack, which can lead to increased bundle processing times for both development and production environments.

Nevertheless, if your entry html file is being generated by Webpack using html-webpack-plugin, you would not be able to include manually the Appmixer SDK on a script tag. In this case you can use add-asset-html-webpack-plugin plugin to include it in your generated html file. Usage example:

var HtmlWebpackPlugin = require('html-webpack-plugin');
var AddAssetHtmlPlugin = require('add-asset-html-webpack-plugin');

module.exports = {
    // ...
    plugins: [
        new HtmlWebpackPlugin({
            template: 'index.html',
        }),

        new AddAssetHtmlPlugin({
            filepath: require.resolve('path/to/appmixer/appmixer.umd.js'),
        }),
    ],
};