Getting Started with the Chamaileon SDK v2

You are reading the documentation for Chamaileon SDK v2. You can find the v1 version here.

What to expect from the v2 Chamaileon SDK

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.

Concept

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.

Hooks

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.

Methods

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.

Using the Chamaileon SDK

SDK Initialization

To use the Chamaileon SDK you need to import it with one of the following methods:

Install from npm

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");

Import from CDN

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.

In a script tag

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.

Authentication

Prior to initialization, you must obtain an accessToken using your API key.

To keep your API keys safe we suggest that you fetch the accessToken from 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.

Getting an access token

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;

Frontend SDK Authentication

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.

Updating Token on Frontend

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",
		red: "#ff5546",
		darkBlue: "#2d3291",
		darkGreen: "#00af6e",
		lightGreen: "#50d791",
		weirdGreen: "#50d791",
		pink: "#ff91a0",
		yellow: "#ffd23c"
	},
};

const accessToken = await getAccessToken();

const chamaileonPlugins = await chamaileonSDK({
	accessToken,
	getAccessToken,
	...whiteLabelConfig,
});

SDK parameters

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
Detailed parameter 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.

Plugin initialization

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,
	}
);

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();

Plugin usage

Fullscreen plugins

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.

Show

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);

Hide

This function will hide the selected plugin instance. It will start the same animation process as the show function but backwards.

pluginInstance.hide();

Show splash screen

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();

Hide splash screen

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();

Example Documents

You might need some example documents (JSONs) during development: