Embed into Your Application

You can natively embed Appmixer UI widgets into your application using the Appmixer UI JavaScript SDK. With just a few lines of code, you gain the ability to integrate not only the integration marketplace but also the fully-featured drag-and-drop automation designer. All widgets are customizable with your theme to align with your app's branding.

Install the Appmixer SDK

To incorporate the Appmixer SDK into your web page, follow these steps:

<script src="https://my.YOUR_TENANT.appmixer.cloud/appmixer/appmixer.js"></script>

Please refer to our Installationpage for additional methods to integrate the Appmixer SDK into your page

Initialize the Appmixer SDK by using the Appmixer API URL provided during the sign-up process. For hosted tenants, the URL follows the pattern: https://api.YOUR_TENANT.appmixer.cloud.

const appmixer = new Appmixer({ baseUrl: 'https://api.YOUR_TENANT.appmixer.cloud' });

Authenticate your end-users

Before presenting integrations to your end-users, it's necessary to first identify them. Achieve this by dynamically creating "Appmixer virtual users" in the background. These virtual users should be linked with the users in your own user management system.

let auth;
try {
    auth = await appmixer.api.authenticateUser(username, usertoken);
    appmixer.set('accessToken', auth.token);
} catch (err) {
    if (err.response && err.response.status === 403) {
        // Virtual user not yet created in Appmixer. Create one.
        try {
            auth = await appmixer.api.signupUser(username, usertoken);
            appmixer.set('accessToken', auth.token);
        } catch (err) {
            alert('Something went wrong creating a virtual user. ' + err.message);
        }
    } else {
        alert('Something went wrong authenticating a virtual user. '+ err.message);
    }
}

Although creating virtual users directly from client-side code is feasible, we recommend enhancing the security of your Appmixer tenant by configuring the API_USER_CREATE_SCOPE system setting to the "admin" string. This ensures that only admin users have the capability to add new users. To create virtual users, you should use the POST /user API endpoint, accompanied by an access token from an Appmixer admin user, from your backend application code. For further details, please consult our documentation at Appmixer Virtual Users.

The username and usertoken serve as credentials to authenticate Appmixer virtual users. It is advisable to utilize an email address (which can be fictional) as the username and a secret token as the usertoken. For instance, you might use MY_USER_ID_IN_MY_APP@yourappdomain.com as the email format. Appmixer does not send emails autonomously to virtual users.

To create a usertoken, consider using the function provided below:

function generateSecureUsertoken(length = 22) {
  const charset = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
  return Array.from(crypto.getRandomValues(new Uint32Array(length)))
    .map((x) => charset[x % charset.length])
    .join('');
}

generateSecureUsertoken()  // ODQMwnwGeZQeXTV5sj3AsR

Please ensure that you securely store these credentials alongside your user records associated with the Appmixer virtual users. This practice enables seamless authentication of your users with Appmixer upon their subsequent visits to your application.

Embed Integration Marketplace

Finally, you can embed your integration marketplace to your application. Utilize the ui.Integrations and ui.Wizard widgets offered by the Appmixer SDK to display the list of available and user activated integrations together with the Wizard web form, facilitating end-users in setting up new integrations or modifying existing ones:

<div id="integrations-placeholder"></div>

const integrations = appmixer.ui.Integrations({
    el: '#integrations-placeholder',
    options: {
        showHeader: true
    }
});
const wizard = appmixer.ui.Wizard();

integrations.on('integration:create', templateId => {
    wizard.close();
    wizard.set('flowId', templateId);
    wizard.open();
});
integrations.on('integration:edit', integrationId => {
    wizard.close();
    wizard.set('flowId', integrationId);
    wizard.open();
});
wizard.on('flow:start-after', () => integrations.reload());
wizard.on('flow:remove-after', () => {
    integrations.reload();
    wizard.close();
});

integrations.open();

Embed Automation Designer

Embedding the Integration Marketplace into your application is just the beginning. You can also incorporate the fully-featured drag-and-drop Automation Designer, granting your end-users unparalleled flexibility in integration and automation. Typically, when integrating the ui.Designer, it's beneficial to include the ui.FlowManager as well. This UI widget presents a list of automations previously created by your users, complete with capabilities for filtering, searching, and managing these automations.

<div id="flow-manager-placeholder"></div>
<div id="designer-placeholder"></div>

const automations = appmixer.ui.FlowManager({
    el: '#flow-manager-placeholder',
    options: {
        menu: [{ event: 'flow:remove', label: 'Remove' }]
    }
});
const designer = appmixer.ui.Designer({
    el: '#designer-placeholder',
    options: {
        showButtonHome: true,
        menu: [
            { event: 'flow:rename', label: 'Rename' }
        ],
        toolbar: [
            ['undo', 'redo'],
            ['zoom-to-fit', 'zoom-in', 'zoom-out'],
            ['logs']
        ]
    }
});

automations.on('flow:open', flowId => {
   designer.close();
   designer.set('flowId', flowId);
   designer.open();
});
designer.on('navigate:flows', () => {
    designer.close();
    automations.reload();
});

automations.open();

Custom Strings and Localization

The text within any UI widget embedded via the Appmixer SDK can be customized or translated into different languages. This is achieved by utilizing the strings object, which can be directly passed to the Appmixer SDK constructor or configured using the set('strings', CHANGES) method:

appmixer.set('strings', {
    ui: {
        flowManager: {
            search: 'Search Automations',
            header: {
                title: 'Automations',
                buttonCreateFlow: 'Create Automation'
            }
        }
    }
});

For more information on customizing text strings and a comprehensive JSON object listing all the text placeholders available for customization, please refer to the Custom Strings page in our documentation.

Custom Theme

The Appmixer SDK offers a straightforward method to customize colors, fonts, and other visual attributes of the rendered UIs. To apply your custom theme, pass your theme object to the Appmixer SDK constructor, or configure it by using the set('theme', YOUR_THEME) method:

appmixer.set('theme', {
    mode: 'light',
    ui: {
        shapes: {
            action: 'action-vertical',
            trigger: 'trigger-vertical'
        }
    },
    variables: {
        font: {
            family: 'serif',
            familyMono: 'monospace',
            size: 16
        },
        colors: {
            background: '#FFFFFF',
            surface: '#FFFDFC',
            separator: '#493843',
            neutral: '#493843',
            primary: '#493843',
            secondary: '#61988E',
            tertiary: '#EABDA8',
            error: '#B3261E',
            warning: '#B56C09',
            success: '#08B685',
            modifier: '#C558CF',
            highlighter: '#FFA500'
        },
        corners: {
            elementRadiusSmall: '0px',
            elementRadiusMedium: '0px',
            elementRadiusLarge: '0px',
            containerRadiusSmall: '0px',
            containerRadiusMedium: '0px',
            containerRadiusLarge: '0px'
        },
        dividers: {
            regular: '2px',
            medium: '4px',
            semibold: '6px',
            bold: '6px',
            extrabold: '9px'
        }
    }
});

For more detailed information, please refer to the Custom Theme page in the documentation.

Demo Applications

For additional code examples on integrating Appmixer into your application, please visit our public repositories:

PreviousBuild a Custom Connector NextMonitor & Troubleshoot

Last updated 6 months ago