Letty Plugin

Документация по установке плагина в ваше приложение

Установка

NPM-пакет

Установить пакет для развертывания плагина в своем приложении можно используя npm-пакет

npm

npm i @letty-email/plugin -E

yarn

yarn add @letty-email/plugin --exact

HTML-script

Coming soon

Инициализация

Шаг 1. Импортируйте плагин

Если используете npm-пакет

import LettyPlugin from '@letty-email/plugin';

в случае встраивания плагина напрямую в html используйте объект window

const LettyPlugin = window.LettyPlugin;

Шаг 2. Создание контейнера

Чтобы редактор отобразился на вашей странице необходимо создать div-элемент с id letty-plugin-container

<div id="letty-plugin-container"></div>

Шаг 3. Аутентификация

Endpoint URL: https://api.kvilla.ru

• Основной пользователь

  • Первый вход

    1. Зарегистрируйте пользователя через POST v1/register

    {
      "email": "[email protected]",
      "password": "string",
    }

    2. Авторизуйтесь через POST v1/login

    {
      "email": "[email protected]",
      "password": "string",
    }

    и получите сессионную куку.

    3. Создайте организацию через POST v1/organizations с параметрами:

    {
      "name": "string",
      "plan_id": 1,
      "with_default_project": true
    }

    в Headers нужно выставить Cookie = полученная сессия из прошлого шага.

    4. Создайте постоянный токен (API key) для организации: POST /v1/organizations/{organizationID}/tokens.

      {
        "name": "string",
        "expires_at": "2025-08-26T00:16:54.409Z"
      }

    5. Сохраните API key у себя на бэкенде.
    6. Передайте ключ в редактор.

• Саблогин

  • Первый вход
    1. Если основной логин ещё не создан или не заходил — выполните шаги 1–5 для основного пользователя.
    2. Зарегистрируйте саблогин проделав шаги 1-2 для саблогина.
    3. Под авторизацией основного пользователя добавьте саблогин в организацию основного пользователя аккаунта: POST /v1/organizations/{organizationID}/users.

      {
        "user_id": "ID саблогина",
        "role_id": 1
      }

    4. Создайте токен для пользователя: POST /v1/organizations/{organizationID}/users/{userID}/tokens.

      {
        "name": "string",
        "expires_at": "2025-08-26T00:16:54.409Z"
      }

    5. Сохраните токен у себя бэкенде и передавайте его в редактор.

• Повторный вход

1. Извлеките сохранённый API key.
2. Передайте ключ в редактор.

Шаг 4. Создание плагина

Инициализируйте редактор в JavaScript-коде:

  import LettyPlugin from '@letty-email/plugin'

  const letty = LettyPlugin.create({
    token: "полученный токен авторизации",
    pluginId: "ID созданного плагина из ЛК",
    locale: "en" либо "ru",
  });

Шаг 5. Запуск редактора

letty.start({
  template: {}, // JSON-письма
  uid: 'Уникальный ID письма в вашей системе',
  templateName?: 'Название письма(если используете встроенную шапку редактора)'
});

Параметры плагина

token

Токен авторизации текущего клиента, который будет использоваться для получения и сохранения блоков, писем и всего, что с ними связано

pluginId

Идентификатор текущей инсталляции плагина, которую вы создали и настроили в ЛК

on

Объект содержащий обработчики событий редактора.

| Событие | Описание | Возвращаемые параметры | | --------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | ready | Редактор загрузился и готов к работе | { json: TemplateJSON; html: string; lastSavedTemplate: TemplateJSON; } | | error | Произошла ошибка | { message: string; details: object|string; } | | notification | Уведомление от редактора | { intent: 'error' | 'info' | 'success' | 'warning'; errorDetails?: object; message: string; } | | autosave | Произошло автосохранение | { json: TemplateJSON; } | | save | Произошло сохранение(Вызывается, в случае если используется внутренняя шапка редактора) | { json: TemplateJSON; } | | exit | Попытка выхода из редактора(Вызывается, в случае если используется внутренняя шапка редактора) | { json: TemplateJSON; } | | toggleGrid | Включена подсветка сетки | { state: boolean; } | | togglePreview | Включен предпросмотр | { state: boolean; json: TemplateJSON; html: string; darkHTML: string; } | | toggleMenu | Включено меню | { menu: EditorMenu | null; } | | history | Добавлено изменение/Произошло перемещение по истории | { hasUndos: boolean; hasRedos: boolean; type: 'change'|'undo'|'redo' } | | uploadImage | В редактор пришло изображение для загрузки | | | openGallery | Открыта галерея | |

container - опциональный

Id элемента в котором будет развернут iframe с редактором По умолчанию letty-plugin-container

locale - опциональный

Язык локализации редактора. Доступные опции: ru и en По умолчанию ru

autosave - опциональный

Параметры автосохранения Варианты значения: true, false, либо { interval: number } По умолчанию true

Методы редактора

start - Запуск редактора

({
  template: TemplateJSON; // Шаблон письма
  uid: string; // Уникальный идентификатор письма
  templateName?: string; // Название письма для вывода во встроенной шапке редактора
}) => void

changeTemplate - Сменить используемый шаблон

(
  template: TemplateJSON, // Шаблон письма
  options?: {
    templateName?: string; // Название письма для вывода во встроенной шапке редактора
    uid?: string; // Уникальный идентификатор письма, на случай, если планируете сменить редактируемое письмо, а не просто контент
  },
) => void

toggleGrid - переключить отображение сетки

Вызывает ивент toggleGrid

(
  state?: boolean, // Состояние сетки. Если значение отсутствует, то выставляется противоположное текущему
) => void

togglePreview - Переключить отображение предпросмотра

Вызывает ивент togglePreview

(
  state?: boolean, // Состояние сетки. Если значение отсутствует, то выставляется противоположное текущему
) => void

toggleMenu - Переключить меню/Выключить меню

Вызывает ивент toggleMenu

(
  menu: EditorMenu | null, // Идентификатор вызываемого меню, либо null, для закрытия открытого меню
) => void

EditorMenu: 'audit', 'guide', 'style', 'blocks'

toggleViewMode - Переключить режим отображения редактора

Вызывает ивент toggleMenu

(
  mode: 'desktop' | 'mobile', // Идентификатор вызываемого меню, либо null, для закрытия открытого меню
) => void

undo - Назад по истории изменений

Вызывает ивент history

() => void

redo - Вперед по истории изменений

Вызывает ивент history

() => void

save - Асинхронный метод для сохранения текущего состояния

Возвращаемые параметры:

{
  json: TemplateJSON,
  html: string,
}

exit - Асинхронный метод для выхода из редактора

{
  json: TemplateJSON,
  html: string,
}

exportContent - Асинхронный метод для получения текущего контента письма

{
  json: TemplateJSON,
  html: string,
}