npm package: @getdraft/plugin
Description: Документация по установке плагина в ваше приложение
Latest version: 1.15.1

# Draft Plugin

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

## Установка

### NPM-пакет

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

#### npm

```
npm i @draft-email/plugin -E
```

#### yarn

```
yarn add @draft-email/plugin --exact
```

### HTML-script

Подключите плагин напрямую через CDN:

```html
<script src="https://eimage.sendsay.ru/app/se/draft/plugin-v1.14.js"></script>
```

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

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

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

```javascript
import DraftPlugin from '@draft-email/plugin';
```

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

```javascript
const DraftPlugin = window.DraftPlugin;
```

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

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

```html
<div id="draft-plugin-container"></div>
```

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

Endpoint URL: Ваш endpoint из ЛК

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

  - **Первый вход**

    1. Авторизуйтесь через `POST` `v1/login` используя админ-логин и пароль

    ```JSON
    {
      "email": "example@example.ru",
      "password": "string",
    }
    ```

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

    Для последующих запросов в Headers нужно выставить Authorization = полученный токен в этом шаге.

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

    ```JSON
    {
      "email": "example@example.ru",
      "password": "string",
    }
    ```

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

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

    4. Добавьте в эту организацию пользователя `POST` `/v1/organizations/{organizationID}/users`:

    ```JSON
    {
      "user_id": "ID созданного юзера",
      "role_id": 1,
    }
    ```

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

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

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

- **Повторный вход**

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

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

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

```javascript
  import DraftPlugin from '@draft-email/plugin'

  const draft = DraftPlugin.create({
    token: "полученный токен авторизации",
    pluginId: "ID созданного плагина из ЛК",
    locale: "en" либо "ru",
    apiUrl: 'https://api.kvilla.ru',
    on: {} // Обработчики событий от редактора
  });
```

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

```javascript
draft.start({
  template: {}, // JSON-письма
  uid: 'Уникальный ID письма в вашей системе',
});
```

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

### **token**

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

### **pluginId**

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

### **on**

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

| Событие         | Описание                                                                                             | Возвращаемые параметры                                                                                                                            |
| --------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ready`         | Редактор загрузился и готов к работе                                                                 | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;html: string;<br>&nbsp;lastSavedTemplate: TemplateJSON;<br>&nbsp;}</code>                           |
| `error`         | Произошла ошибка                                                                                     | <code>{<br>&nbsp;message: string;<br>&nbsp;details: object\|string;<br>&nbsp;}</code>                                                             |
| `notification`  | Уведомление от редактора                                                                             | <code>{<br>&nbsp;intent: 'error' \| 'info' \| 'success' \| 'warning';<br>&nbsp;errorDetails?: object;<br>&nbsp;message: string;<br>&nbsp;}</code> |
| `autosave`      | Произошло автосохранение                                                                             | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;}</code>                                                                                            |
| `save`          | Произошло сохранение<br>_(Вызывается, в случае если используется внутренняя шапка редактора)_        | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;}</code>                                                                                            |
| `exit`          | Попытка выхода из редактора<br>_(Вызывается, в случае если используется внутренняя шапка редактора)_ | <code>{<br>&nbsp;json: TemplateJSON;<br>&nbsp;}</code>                                                                                            |
| `toggleGrid`    | Включена подсветка сетки                                                                             | <code>{<br>&nbsp;state: boolean;<br>&nbsp;}</code>                                                                                                |
| `togglePreview` | Включен предпросмотр                                                                                 | <code>{<br>&nbsp;state: boolean;<br>&nbsp;json: TemplateJSON;<br>&nbsp;html: string;<br>&nbsp;darkHTML: string;<br>&nbsp;}</code>                 |
| `toggleMenu`    | Включено меню                                                                                        | <code>{<br>&nbsp;menu: [EditorMenu](#EditorMenu) \| null;<br>&nbsp;}</code>                                                                       |
| `history`       | Добавлено изменение/Произошло перемещение по истории                                                 | <code>{<br>&nbsp;hasUndos: boolean;<br>&nbsp;hasRedos: boolean;<br>&nbsp;type: 'change'\|'undo'\|'redo'<br>&nbsp;}</code>                         |
| `uploadImage`   | В редактор пришло изображение для загрузки                                                           |                                                                                                                                                   |
| `openGallery`   | Открыта галерея                                                                                      |                                                                                                                                                   |
| `loadPersonalization` | Редактор запрашивает данные персонализации. Асинхронный обработчик — должен вернуть словарь персонализации | Обработчик должен вернуть: <code>Promise<{<br>&nbsp;items: Array&lt;<br>&nbsp;&nbsp;{ name: string; value: string }<br>&nbsp;&nbsp;\| { groupName: string; items: Array&lt;{ name: string; value: string }&gt; }<br>&nbsp;&gt;<br>}></code> |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

<a name="EditorMenu"></a>

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

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

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

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

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

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

```typescript
() => void
```

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

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

```typescript
() => void
```

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

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

```typescript
{
  json: TemplateJSON,
  html: string,
}
```

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

```typescript
{
  json: TemplateJSON,
  html: string,
}
```

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

```typescript
{
  json: TemplateJSON,
  html: string,
}
```