@chec/integration-configuration-sdk
v0.0.8
Published
This SDK is available to help build custom configuration apps for integrations that work with Commerce.js infrastructure and appear within the Chec Dashboard.
Downloads
8
Keywords
Readme
Integration Configuration App SDK
This SDK is available to help build custom configuration apps for integrations that work with Commerce.js infrastructure and appear within the Chec Dashboard.
Installation
yarn add @chec/integration-configuration-sdk
Usage
There are two options for controlling the configuration of an integration. You can either choose to create a completely custom web app that will appear within the Chec Dashboard (the "frame" option), or you can dynamically update the form schema of the integration template, and react to input and events triggered by the user (the "controlled" option).
Establishing a connection to the Chec Dashboard
As your app will be brought in and shown during a user session in the Chec Dashboard, the app will need to establish a connection to the dashboard:
import { createSDK, ConfigSDK } from '@chec/integration-configuration-sdk';
createSDK().then((sdk: ConfigSDK) => {
// Typescript is shown, but you can remove the references to `ConfigSDK` to convert to native JS
})
Next, you will need to decide how you will influence the configuration screen by choosing one of the options detailed above.
"Controlled" option
This option does not require your app to product any user interface. Instead, you can use the SDK to update the form schema that the Chec Dashboard uses to display a form:
import { createSDK, SchemaFieldTypes } from '@chec/integration-configuration-sdk';
(async () => {
const sdk = await createSDK();
sdk.setSchema([
{
key: 'name',
type: SchemaFieldTypes.ShortText,
label: 'Your name',
},
]);
})();
When the configuration screen renders in the Chec Dashboard, a form will display that matches the schema set by your app. As the user fills in the form, the integration config is updated as usual.
Watching for events
You can register an event handler that is called when the configuration changes:
import { createSDK } from '@chec/integration-configuration-sdk';
(async () => {
const sdk = await createSDK();
sdk.onConfigUpdate((config: object) => {
console.log(config);
});
})();
You can render buttons and watch for clicks:
import { createSDK, SchemaFieldTypes } from '@chec/integration-configuration-sdk';
(async () => {
const sdk = await createSDK();
sdk.setSchema([
{
key: 'my_button',
type: SchemaFieldTypes.Button,
label: 'Click me',
},
]);
sdk.on('click', 'my_button', () => {
console.log('Clicked!');
});
})();
You can also set config attributes directly using setConfig
. Configuration set this way is merged with existing
configuration.
import { createSDK } from '@chec/integration-configuration-sdk';
(async () => {
const sdk = await createSDK();
sdk.setConfig({
my_custom_option: 'Hello world!',
});
})();
Using typescript to ensure form schema matches configuration
This SDK provides types for form schema to help create valid form schemas for the Chec Dashboard. Additionally, you can provide a type definition for your configuration to perform type checking on the schema to ensure it matches the configuration you're expecting. For example, say you want to configure your integration with the following config:
export default interface MyIntegrationConfiguration {
customerMessage: string
}
You may choose to create this in it's own file at the root of the project so it can be shared by the configuration app
and the integration, that will have access to the config with (await context.integration()).config
.
Then you can create a schema like so:
import { Schema, SchemaFieldTypes } from '@chec/integration-configuration-sdk';
import MyIntegrationConfiguration from '../config';
const schema: Schema<MyIntegrationConfiguration> = [
{
key: 'customerMessage',
label: 'Message to display to the customer',
type: SchemaFieldTypes.ShortText,
}
];
Typescript with throw an error if the value for key
does not exist in your configuration interface, avoiding potential
typos and mistakes. Additionally, you can ensure the schema matches your configuration only when you set it:
import { createSDK } from '@chec/integration-configuration-sdk';
import MyIntegrationConfiguration from '../config';
(async () => {
const sdk = await createSDK<MyIntegrationConfiguration>();
sdk.setSchema([
{
key: 'customerMessage',
label: 'Message to display to the customer',
type: SchemaFieldTypes.ShortText,
}
]);
})();
"Frame" option
You can build a custom UI to configure your app, and set the resulting configuration using the sdk.setConfig
API
detailed above. The Chec dashboard will render your app in the configuration panel, even when using the "controlled"
option, but your app is hidden until the dashboard knows the height of the content that your app renders. You can
report the height of your app using the SDK, or turn on the automatic height detection system:
(async () => {
document.body.innerText = 'Hello world!';
const sdk = await createSDK();
sdk.setHeight(20); // In pixels
// OR
sdk.enableAutoResize();
})();
The UI library used by the Chec dashboard is open source and available for use by your app if you're building with Vue:
https://github.com/chec/ui-library - Storybook (demo site)