Chamaileon SDK

Appearance

Chamaileon SDK v2 – Quickstart ​

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

Integrate a powerful, collaborative email editor into your app in minutes.

You can find the plugin-interface open-source project here.

0. Prerequisites ​

  • API key (get from SDK dashboard)
  • Your domain added to the environment

1. Backend Setup: Create a Secure Token Endpoint ​

SECURITY BEST PRACTICE

Your API key is a secret and should never be exposed in frontend code. To generate an accessToken securely, you must create a backend endpoint that proxies the request to the Chamaileon API. Your frontend will then call your backend endpoint, not the Chamaileon API directly.

The following examples show how to create a minimal backend endpoint that securely generates an accessToken and how the frontend should call it to get the token needed for the next step.

DOMAIN WHITELISTING

Remember to add your application's domain (e.g., yourapp.com) to your SDK environment's whitelist in the SDK Dashboard. For local development with a server, include localhost with the correct port (e.g., http://localhost:3000). If you open a static HTML file directly in the browser, you might only need to add localhost. If you are developing on Windows Subsystem for Linux (WSL), you might also need to add wsl.localhost.

javascript
// server.js
// Make sure to install dependencies:
// npm install express node-fetch@2 dotenv

require('dotenv').config(); // Use dotenv for local development
const express = require('express');
const cors = require('cors');

const app = express();
app.use(cors()); // This enables CORS for all origins

const port = 3000;

const CHAMAILEON_API_KEY = process.env.CHAMAILEON_API_KEY;
const CHAMAILEON_API_URL = 'https://sdk-api.chamaileon.io/api/v2/tokens/generate';

app.get('/api/chamaileon-token', async (req, res) => {
  if (!CHAMAILEON_API_KEY) {
    return res.status(500).json({ error: 'API key not configured on the server.' });
  }

  try {
    const apiResponse = await fetch(CHAMAILEON_API_URL, {
      method: 'GET',
      headers: { 'Authorization': `Bearer ${CHAMAILEON_API_KEY}` },
    });

    if (!apiResponse.ok) {
      throw new Error(`Chamaileon API error: ${apiResponse.statusText}`);
    }

    const data = await apiResponse.json();
    res.json({ accessToken: data.result });
  } catch (error) {
    console.error('Token generation error:', error);
    res.status(500).json({ error: 'Failed to generate token.' });
  }
});

app.listen(port, () => {
  console.log(`Backend server listening at http://localhost:${port}`);
});
php
<?php
// /api/chamaileon-token.php

// For local development, you can use a library like vlucas/phpdotenv
// to load variables from a .env file.

header('Content-Type: application/json');

$apiKey = getenv('CHAMAILEON_API_KEY');
if (!$apiKey) {
    http_response_code(500);
    echo json_encode(['error' => 'API key not configured on the server.']);
    exit;
}

$apiUrl = 'https://sdk-api.chamaileon.io/api/v2/tokens/generate';
$options = ['http' => ['header'  => "Authorization: Bearer " . $apiKey, 'method'  => 'GET']];
$context = stream_context_create($options);
$result = file_get_contents($apiUrl, false, $context);

if ($result === FALSE) {
    http_response_code(500);
    echo json_encode(['error' => 'Failed to generate token.']);
    exit;
}

$response = json_decode($result, true);
echo json_encode(['accessToken' => $response['result']]);
?>
python
# app.py
# Make sure to install dependencies:
# pip install Flask requests python-dotenv

import os
import requests
from flask import Flask, jsonify, make_response
from dotenv import load_dotenv

load_dotenv() # Use dotenv for local development

app = Flask(__name__)

CHAMAILEON_API_KEY = os.getenv('CHAMAILEON_API_KEY')
CHAMAILEON_API_URL = 'https://sdk-api.chamaileon.io/api/v2/tokens/generate'

@app.route('/api/chamaileon-token')
def get_chamaileon_token():
    if not CHAMAILEON_API_KEY:
        return make_response(jsonify({'error': 'API key not configured on the server.'}), 500)

    try:
        headers = {'Authorization': f'Bearer {CHAMAILEON_API_KEY}'}
        response = requests.get(CHAMAILEON_API_URL, headers=headers)
        response.raise_for_status() # Raises an HTTPError for bad responses (4xx or 5xx)
        data = response.json()
        return jsonify({'accessToken': data['result']})
    except requests.exceptions.RequestException as e:
        print(f'Token generation error: {e}')
        return make_response(jsonify({'error': 'Failed to generate token.'}), 500)
sh
curl -X GET "https://sdk-api.chamaileon.io/api/v1/tokens/generate" \
-H "Authorization: Bearer CHAMAILEON_API_KEY"

2. Frontend Setup ​

Step 1. Install the SDK ​

The Chamaileon SDK is a frontend library. Choose one of the following methods to add it to your web application.

For Projects with a Build Tool (e.g., Vite, Webpack) ​

Install the package from npm

sh
npm i @chamaileon-sdk/plugins

Import the module in your code

javascript
import chamaileonSdk from "@chamaileon-sdk/plugins";

For Static HTML or Prototypes (via CDN) ​

For projects without a build system, you can load the SDK directly from our CDN.

ES Module (Recommended)

html
<script type="module">
  import chamaileonSdk from "https://cdn.chamaileon.io/sdk/1.1.4/es/plugins.js";
</script>

UMD (Classic Script)

html
<script src="https://cdn.chamaileon.io/sdk/1.1.4/umd/plugins.js"></script>

Step 2. Initialize SDK ​

javascript
// This function will run on your frontend.
// It calls YOUR backend endpoint to get the token.
async function fetchAccessToken() {
  // Replace with the URL of your backend endpoint
  const response = await fetch('/api/chamaileon-token');
  if (!response.ok) {
    throw new Error('Failed to fetch access token from your backend.');
  }
  const { accessToken } = await response.json();
  return accessToken;
}

// First, get an initial token.
const accessToken = await fetchAccessToken();

// Then, initialize the SDK.
// Pass the token for the initial load, and the function for automatic refresh.
const chamaileonPlugins = await chamaileonSdk({
  accessToken,
  getAccessToken: fetchAccessToken
});

Step 3. Create Your First Plugin ​

js
const pluginInstance = await chamaileonPlugins.createFullscreenPlugin({
  plugin: "editor", // or another plugin name
  data: {},
  settings: {},
  hooks: {}
});

// show it
pluginInstance.show();

You should now see the plugin!

Next Steps ​