You are reading the documentation for Chamaileon SDK v2. You can find the v1 version here.
Our goal with the second version of the Chamaileon SDK is to provide blazing fast performance and a consistent developer experience.
We completely rewrote the plugin interface to achieve this and made it open-source as well. It's the base of our SDK and we use it to communicate through the postMessage API.
You can find the plugin-interface open-source project here.
All of the plugins are capable of changing their settings and data on the fly. With this we can achieve a smooth user experience. In practice you can initialize any plugin once and use the same instance during the entire user session. You only have to update the data or settings and you don't have to wait for the plugin to re-initialize from zero.
You can also decide to use each plugin in fullscreen or inline mode with the same settings and data.
Before we start the detailed description of the SDK and each plugin, let's see how the interface works. Reading this will help you optimize each plugin based on your unique needs.
After initializing the Chamaileon SDK, you have to create each plugin one by one. This process is described later in this document.
The created plugin will use hooks to communicate with your host environment. You have to create these functions that will be called at certain events inside the plugin. We call these functions hooks. You can read more about these and find their names inside the chosen plugin's documentation.
The created plugin will return methods that you can use to interact with the plugin from your host environment. You can read more about these and find their names inside the chosen plugin's documentation.
To use the Chamaileon SDK you need to import it with one of the following methods:
You can install the Chamaileon SDK package from https://npmjs.com like this:
npm i @chamaileon-sdk/plugins
And use it like this
import chamaileonSdk from "@chamaileon-sdk/plugins";
Or like this
const chamaileonSdk = require("@chamaileon-sdk/plugins");
You can also import the Chamaileon SDK package from our CDN like this
<script type="module">
import chamaileonSdk from "https://cdn.chamaileon.io/sdk/##CURRENT_VERSION##/es/plugins.js";
</script>
You can find the newest version number here.
You can also use it in a script tag from our CDN like this
<script src="https://cdn.chamaileon.io/sdk/##CURRENT_VERSION##/umd/plugins.js"></script>
With this we add the library to the window object so you can access it like this:
window.chamaileonSdk({...})
You can find the newest version number here.
Prior to initialization, you must obtain an accessToken using your API key.
To keep your API keys safe we suggest that you fetch the
accessTokenfrom your backend. Then you only have to send this generated token to the client side.
The token is only valid up to 24 hours.
Make sure you added your domain into your API key's environment. Go to the SDK dashboard, select your environment and go to the domains section.
Pass your API key to the Authorization header as shown on the example below
const accessTokenRequest = fetch("https://sdk-api.chamaileon.io/api/v1/tokens/generate", {
method: "GET",
headers: {
"Authorization": `Bearer ${apiKey}`,
}
});
const accessTokenResponse = await accessTokenRequest.json();
const accessToken = accessTokenResponse.result;
You have to pass your accessToken to the SDK as a config parameter. The SDK needs a valid token and will check it on initialization and on every plugin creation.
When you initialize your SDK it automatically stores your token. As long as you have the page open it uses this access token and authenticates with it until it's expired.
To enable automatic token refresh in the SDK we advise you to pass a function named getAccessToken as a config parameter. This function is called on every plugin creation if your token is expired. The function should return the plain accessToken value as a string.
import chamaileonSDK from "@chamaileon-sdk/plugins";
async function getAccessToken(){
const accessTokenRequest = await fetch(`Your/backend/access/token/generator/url`, {
method: "GET",
});
if(accessTokenRequest.ok){
const accessTokenResponse = await accessTokenRequest.json();
return accessTokenResponse.result;
}
}
const whiteLabelConfig = {
locale: "en", // If you need other languages please contact us.
urls: {
splashScreen: "https://chamaileon-sdk.github.io/splashscreen-and-logo-examples/splashScreen.html",
createLogoJS: "https://chamaileon-sdk.github.io/splashscreen-and-logo-examples/createLogo.js"
},
colors: {
primary: "#2D3291",
secondary: "#009f4a",
accent: '#82B1FF',
error: '#FF5252',
info: '#2196F3',
success: '#4CAF50',
warning: '#FFC107',
},
font: {
url: "https://fonts.googleapis.com/css?family=Roboto:300,400,500,700",
family: "'Roboto', sans-serif",
},
};
const accessToken = await getAccessToken();
const chamaileonPlugins = await chamaileonSDK({
accessToken,
getAccessToken,
...whiteLabelConfig,
});
| Property | Type | Description |
|---|---|---|
| accessToken | string | used to authenticate inside the SDK |
| getAccessToken | function | returns a newly generated access token |
| locale | string | The used language pack |
| urls | object | #see detailed explanation |
| colors | object | #see detailed explanation |
| font | object | #see detailed explanation |
| Property | Type | Description |
|---|---|---|
| urls.splashScreen | string | An url of a html file which will be displayed in an iframe until the plugins load. You can find examples here. |
| urls.createLogoJS | string | An url of a hosted javascript file with a function named createLogo() in it. It is up to you how you customize this. You can do any kind of fancy transitions with JS. You can find examples here. |
| colors | object | Your own theme colors. The colors property represents the Vuetify Theme Configuration object. In most cases it's enough if you set up the primary color. |
| font.url | string | An url of the font file you want to use in our plugins. |
| font.family | string | The font family you want to use in our plugins. |
You can navigate to each plugin's documentation by using the links on the left-hand-side.
We also have a migration guide that you can follow to migrate from v1 to v2. You can find it in the left-hand-side menu as well.
After the successful initialization the chamaileonSDK will return an object with two create functions and a destroy function. You can initialize our plugins included in the SDK by invoking those functions. With the createFullscreenPlugin function you can create a fullscreen plugin and with the createInlinePlugin you can create an inline plugin.
const fullScreenPluginInstance = await chamaileonPlugins.createFullscreenPlugin({
plugin: "plugin-name",
data: {},
settings: {},
hooks: {},
});
const inlinePluginInstance = await chamaileonPlugins.createInlinePlugin(
{
plugin: "plugin-name",
data: {},
settings: {},
hooks: {},
},
{
container: HTMLElement,
dimensions: {
width: "100%"
height: "100%",
scale: 1,
}
}
);
The destroy function destroys every plugin instance and removes them from the DOM including their the wrapper element. After this it also destroys the SDK instance as well.
chamaileonPlugins.destroy();
Updates the hooks inside the plugin instance on the fly.
await pluginInstance.methods.updateHooks({ hooks, resetHooks });
The updateHooks object parameter has the following parameters:
| Property | Type | Description |
|---|---|---|
| hooks | object | The same object format should be used as at the initialization stage. |
| resetHooks | boolean | Chooses if you want to reset the already configured hooks or just want to add to them. Default: false |
Starting context
const onSave = () => {};
const onDelete = () => {};
const onFail = () => {};
const activeHooks = [];
const pluginInterface = await createFullscreenPlugin(...);
// For this example let's say that we sent
// the "onFail" hook with the init function
pluginInterface.methods.updateHooks = (hooks) => {
activeHooks = hooks;
}
Update the hooks while keeping the already defined ones
await pluginInterface.methods.updateHooks({ hooks: { onSave } });
// after the method call the activeHooks should be equal with ["onSave", "onFail", "error"];
If a hook is passed with it's value set to
nullinstead of it being afunctionthen it will be removed from the list of available hooks inside the plugin.
Update the hooks and only keep the new ones
await pluginInterface.methods.updateHooks({ hooks: { onDelete }, resetHooks: true });
// after the method call the activeHooks should be equal with ["onDelete", "error"];
The fullscreen plugin instance will return some default functions that can be used to show/hide the plugin itself or to show/hide the splash screen inside the plugin instance.
This function will show the selected plugin instance. The plugin's animation start position, opacity, scale and the animation's duration can be set. This function will return a Promise that will be resolved when the animation is finished.
For a smooth animation you should update the plugin before or after the show function call and not during the transition process.
const config: {
x: "-100vw", // position on the X axis where the show animation starts
y: "0px", // position on the Y axis where the show animation starts
opacity: 0.5, // opacity at the start of the show animation
scale: 1, // scale at the start of the show animation
time: 450 // full duration of the show animation in milliseconds
}
pluginInstance.show(config);
This function will hide the selected plugin instance. It will start the same animation process as the show function but backwards.
pluginInstance.hide();
You can show a splash screen inside the plugin instance by calling this function. You should this when the plugin is loading new data or settings and the plugin is already visible on the screen.
pluginInstance.showSplashScreen();
You can show a splash screen inside the plugin instance by calling this function. You should call this when every new data and setting has already finished loading into the plugin.
pluginInstance.hideSplashScreen();
You might need some example documents (JSONs) during development: