Перейти к содержанию

Встраивание виджета чата через iframe

Виджет чата Webim (со стороны посетителя) можно встроить в страницы веб-сайта клиента через iframe.

Настройка nginx

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

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

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

    N.B.

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

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

    Путь зависит от особенностей начальной установки, например, он может выглядеть так:

    /etc/nginx/webim-common/
    
  2. В текстовом редакторе добавьте в файл iframe.conf выдачу правильных заголовков (Response Headers). Вместо https://www.domain.local нужно вставить нужный Вам URL, вместо www.domain.local — нужный Вам домен. Пример файла настроек:

    add_header Content-Security-Policy "frame-ancestors 'self' localhost https://www.domain.local";
    

    X-Frame-Options: ALLOW-FROM в актуальных Chrome и Firefox не работает: браузер игнорирует такой заголовок. Встраивание разрешает frame-ancestors. Подробнее о frame-ancestors, CSP и наследовании заголовков — в статье Настройка Content-Security-Policy.

  3. Найдите основной файл настроек nginx для Webim. Путь зависит от особенностей начальной установки, например, он может выглядеть так:

    /etc/nginx/sites-available/webim-hosted.conf
    

    Во все секции location, отвечающие за URL виджета чата посетителя, который Вы хотите сделать доступным в iframe, вставьте строку:

    include /etc/nginx/webim-common/iframe.conf;
    

    Удалите из этих location строки, которые могут влиять на заголовки X-Frame-Options и Content-Security-Policy.

    Примерный список секций location:

    • ^(\/l\/v\/(?:m\/)?history|\/l\/[vo]\/get-history|\/internal\/history\/.+|\/api\/history\/v[1-9]\d*\/.+)$

    • ^(\/api\/history\/(?:m\/)?history|\/l\/[vo]\/get-history|\/internal\/history\/.+|\/api\/history\/v[1-9]\d*\/.+)$

    • \/services\/history\/v\d+\/(?:m|w)\/(?:visitor|agent|old-visitor)

    • \/api\/history\/service\/v\d+\/

    • (\/avatar|department_logo|chat_logo|invitation_avatar|visitor_avatars|ainvite_avatar|site_logo|site_preview).*\.(jpg|jpeg|gif|png|svg|webp)$

    • \.(eot|ttf|woff)$

    • ^\/(?!x)(?!l)(?!ws)(?!agent)(?!webim)(?!image-robot)(?!images)(?!cdn)(?!images)(?!robots.txt)(?!api).+\.(ico|gif|png|jpe?g|svg|webp|css|js|htm|html)$

    • ^\/js\/backend\/emoji-annotations\/

    • ^\/(?!x)(?!l)(?!ws)(?!agent)(?!webim)(?!image-robot)(?!images)(?!cd2)(?!cdn)(?!cd)(?!images)(?!robots.txt)(?!manifest.json)(?!browserconfig.xml)(?!api)(?!.+-status)(?!.+-ping)

    • ^\/(images|css)(\/.+)$

    • ^\/cd\/default\/sounds\/.+$

    • ^\/cd\/(.+?)\/sounds\/.+$

    • \/ws\/

    • \/l\/(v|o)\/download.*\.(png|gif|jpe?g|svg|webp|pdf|doc)$

    • \/l\/(v|o)\/download\/.*?([^\/]+)$

    • \/l\/v\/

    • \/l\/

    • \/button\.js$

    • \/js\/button\.js$

    • \/webim\/button(?:\.php)?

    • \/js\/v\/all-settings-([-\w\d]+)\.js

    • \/css\/v\/chat-([-\w\d]+)\.css

    • \/css\/v\/invitation-([-\w\d]+)\.css

    • \.(jpg|jpeg|gif|png|svg|webp|css|js)$

    Пример правильно отредактированной секции location (конкретные пути могут отличаться в Вашей установке):

      location ~ \/l\/v\/  {
          proxy_pass http://chat_backend;
          include /etc/nginx/webim-common/python_proxy_params.conf;
          include /etc/nginx/webim-common/iframe.conf;
      }
    
  4. После окончания настройки нужно перезагрузить сервис nginx.

Тег фрейма

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

<div style="position: fixed; top: 0; bottom: 0; right: 0; border: 0;">
  <iframe name="Webim Chat Widget"
          src="https://mycompany.webim.ru/visitor/chat"
          height="360" width="240"
          scrolling="no"
          frameborder="1" align="right">
  </iframe>
</div>

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

  • В поле src требуется вписать URL виджета чата:

    • Пример URL для облачного аккаунта:
    https://mycompany.webim.ru/visitor/chat
    
    • Пример URL для аккаунта, размещенного не на серверах Webim:
    https://chat.domain.local/visitor/chat
    
  • В поле height указывается высота встраиваемого окна.

  • В поле width указывается ширина встраиваемого окна.

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

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

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

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

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

  // ...
}

N.B.

Вместо origin_url должен быть указан URL виджета чата. В event.origin есть схема, хост и порт, но нет пути страницы. При несоответствии origin адресу виджета обработка этого события не должна продолжаться.

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

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