Встраивание административного интерфейса через iframe

Административный интерфейс Webim можно встроить в страницы какого-либо иного веб-сервиса через iframe. Наиболее часто данная функция используется для встраивания в сторонний CRM с веб-интерфейсом. Такое использование повышает эффективность работы оператора, потому что ему больше не требуется держать открытыми две вкладки и переключаться между ними.

Настройка nginx

Для облачных клиентов, у которых сервис Webim расположен на серверах компании ООО "ВЕБИМ.РУ", требуется обратиться в службу технической поддержки Webim.

Для корректной настройки требуется выполнить следующие пункты:

В настройках веб-сервера nginx, который обслуживает ваш аккаунт Webim, нужно изменить настройки, отвечающие за выдачу контента через фреймы.

N.B.

Необходимо редактировать настройки сервера, который обслуживает именно chat.mycompany.com, на котором расположен сервис Webim, а не CRM, в которую будет встроен iframe.

Найдите директорию с настройками nginx и создайте в этой директории файл iframe.conf.

Путь зависит от особенностей начальной установки, например, он может выглядеть так:
```
/etc/nginx/conf/webim-config/common
```
В текстовом редакторе добавьте в файл iframe.conf выдачу правильных заголовков (Response Headers). Вместо https://crm.company.com нужно вставить URL на сайт(ы), куда будет встраиваться сервис Webim. Также файл не должен содержать других ограничений, например, frame-ancestors: 'self'. Пример файла настроек:
```
add_header X-Frame-Options "ALLOW-FROM localhost https://crm.company.com";
add_header Content-Security-Policy "frame-ancestors localhost crm.company.com";
```
Найдите основной файл настроек nginx для Webim. Путь зависит от особенностей начальной установки, например, он может выглядеть так:
```
/etc/nginx/conf/webim-config/sites-available/webim.conf
```
Во все секции location, отвечающие за URL административного интерфейса, который Вы хотите сделать доступным в iframe, вставьте строку:
```
include /etc/nginx/webim-config/common/iframe.conf;
```
Удалите из этих location строки, которые могут влиять на заголовки X-Frame-Options и Content-Security-Policy

Примерный список секций location:
- /
- /api/speller/v2/check
- ^(/l/v/(?:m/)?history|/l/[vo]/get-history|/internal/history/.+|/api/history/v[1-9]d*/.+)$
- ^/webim/images(/avatar|department_logo|visitor_avatars|ainvite_avatar|site_logo|site_preview).*.(jpg|jpeg|gif|png)$
- (get-image).php$
- ^/(?!x)(?!l)(?!ws)(?!webim)(?!image-robot)(?!images)(?!cd2)(?!cdn)(?!cd)(?!images)(?!robots.txt)(?!api).+.(ico|gif|png|jpg|css|js|htm|html)$
- ^/(images|css)(/.+)$
- ^/webim/(images|css)(/.+)$
- /l/(v|o)/download.*.(png|gif|jpe?g|webp|pdf|doc)$
- /l/(v|o)/download/.*?([^/]+)$
- /l/
- /webim/operator.+.php$
- .php$
- >.(jpg|jpeg|gif|png|css|js)$
- ^/api
Пример правильно отредактированной секции location:

location / { root $php_root; index index.php; include /etc/nginx/webim-config/common/iframe.conf; }
После окончания настройки нужно перезагрузить сервис nginx.

Тег фрейма

Для того, чтобы на нужной странице работал iframe, в HTML-код страницы необходимо добавить тег iframe. Пример:

<div style="position: fixed; top: 0; bottom: 0; right: 0; border=0;">
  <iframe name="Webim Control Panel"
          src="https://mycompany.webim.ru/agent/"
          height="100%" width="940"
          scrolling="no"
          frameborder="1" align="right">
  </iframe>
</div>

Данные, указываемые в теге iframe:

В поле src требуется вписать URL РМО оператора:
- Пример URL для облачного аккаунта:
```
https://mycompany.webim.ru/agent/
```
- Пример URL для аккаунта, размещенного не на серверах Webim:
```
https://chat.mycompany.com/agent/
```
В поле height указывается высота встраиваемого окна. Рекомендуемое значение: 100%.
В поле width указывается высота встраиваемого окна. Рекомендуемая ширина без потери функциональности на РМО: 940. Минимальная рекомендуемая ширина с потерей функциональности на РМО: 792.

Взаимодействие между окнами

Для взаимодействия между CRM, в которую встраивается сервис, и Webim через iframe существует метод postMessage. Он позволяет отправлять между окнами события, содержащие объекты (object).

Для активации рассылки событий требуется добавить адреса страниц, на которые будут отправляться события, в конфигурации аккаунта:

Если у вас облачный аккаунт, обратитесь в службу технической поддержки Webim для добавления в конфигурацию аккаунта URL на которые требуется отправлять события.
Если сервис Webim размещен на ваших серверах, требуется добавить в поле operator_iframe_allowed_parent_origin в конфигурации аккаунта URL на которые требуется отправлять события.

Для того, чтобы сайт, в который встраивается Webim, мог получать события, на нём должен быть активен слушатель события message. При получении события также должен вызываться его обработчик, который реализует требуемые функции. Из соображений безопасности требуется проверять адрес, с которого приходит событие. Оно передается в поле origin. Пример реализации:

window.addEventListener("message", receiveMessage, false);

function receiveMessage(event) {
  if (event.origin !== "origin_url")
    return Exception();

  // ...
}

N.B.

Вместо origin_url должен быть указан URL РМО оператора. При несоответствии origin адресу РМО обработка этого события не должна продолжаться.

Для того, чтобы определить события, которые требуется передавать в CRM из Webim и в обратном направлении, следует обратиться к нашим менеджерам, чтобы подыскать решение, подходящее именно Вам.

Работа с внешними ссылками

Все внешние ссылки при работе с iframe будут продолжать открываться в новом окне, а не внутри iframe. Например, если посетитель отправит ссылку на внешний ресурс или картинку, находящуюся на внешнем ресурсе, нажатие на эту ссылку или картинку приведёт к открытию в браузере нового окна.

Внешний вид страницы с iframe