Synchra.24
menu_bookДакументацыя
Практические материалы по запуску и развитию

Здесь собраны инструкции по запуску, разработке внутренних сценариев и встраиванию собственных инструментов в рабочий контур компании.

folderУбудаваныя сэрвісы

Фішкі і карткі

Дзе паказваць фішкі, як наладзіць іх вышыню і доступ супрацоўнікаў.

Пераклад пакуль недаступны. Паказаны арыгінал.

Назначение и виджет дашборда

В настройках сервиса выберите Назначение сервиса:

  • Обычный сервис — отдельный пункт в меню сервисов.
  • Виджет дашборда — карточка в рабочем пространстве сотрудника вместо пункта меню.

После выбора виджета появляется плашка Настройки виджета. В ней независимо задаются Разрешить в веб-версии и Разрешить в мобильной версии. Эти переключатели доступны при создании и в настройках сервиса. Мобильный показ по умолчанию включён, в том числе у существующих сервисов; настройка веб-показа сохраняет прежнее значение. Если выключить оба переключателя, виджет не будет доступен сотрудникам ни на одной платформе, но останется в списке администратора для настройки. Данные и опубликованный код не удаляются.

Включите Автоматическая высота, чтобы размер подстраивался под содержимое одновременно в вебе и мобильном приложении: при появлении полей карточка растёт, при сворачивании уменьшается. Прокручивается общая страница приложения. По умолчанию настройка выключена и существующие виджеты сохраняют свои размеры.

При выключенной автоматической высоте доступны два независимых слайдера:

  • Высота на мобильном — от 60 до 800 логических пикселей, шаг 10; стандартная высота 100.
  • Высота в веб-версии — от 120 до 800 пикселей, шаг 20; стандартная высота 280.

Заголовок карточки в высоту содержимого не входит. Кнопка По умолчанию возвращает оба стандартных размера. Включение автоматической высоты не стирает ручные значения: после выключения переключателя они возвращаются.

В мобильном приложении виджет использует тот же WebView и нативный мост, что и обычный сервис: SDK, контекст компании, артефакты, диалоги и другие поддержанные методы продолжают работать. Удержание заголовка открывает настройку рабочего пространства: виджет можно скрыть, вернуть и передвинуть. В этом режиме сервисные виджеты показывают своё содержимое, как и встроенные карточки. Чтобы переместить сервисный виджет, удерживайте его заголовок или любую область содержимого, затем перетащите карточку. Кнопки, поля и внутренняя прокрутка виджета в этом режиме не реагируют на касания; переключатель видимости рядом с заголовком остаётся доступен. После нажатия Готово обычное взаимодействие возвращается. Положение и видимость сохраняются для сотрудника. Вне режима редактирования скрытый виджет не запускается. Ошибка загрузки показывает кнопку повторной попытки внутри карточки.

В веб-дашборде виджет появляется только при включённом «Разрешить в веб-версии». Нужны действующая лицензия Приложения, включённый сервис, доступ сотрудника и опубликованный код. Название, высота и содержимое берутся из сервиса; черновик не показывается. Управление порядком и видимостью находится в Виджеты дашборда, настройки сохраняются в этом браузере отдельно для пользователя и компании.

В веб-версии виджеты поддерживаются для сервисов HTML, CSS и JavaScript. Сервисы по внешнему URL доступны как виджеты только на мобильных устройствах: удалённая страница не переносится в Shadow DOM.

Автоматическая высота и код виджета

Автоматический размер работает во всех местах размещения виджетов; обычные сервисы остаются без изменений. В мобильном приложении нужна версия с поддержкой автоматической высоты. Для мобильного виджета по внешнему URL размер также определяется по содержимому страницы. Веб-виджеты по внешнему URL по-прежнему не поддерживаются.

Размещайте содержимое в обычном потоке документа. Не задавайте фиксированную высоту, 100vh или высоту в процентах от окна для основного содержимого: такой размер зависит от окна, а не от полей. Внутренние области с заданной высотой и собственной прокруткой, например редакторы текста, сохраняют своё поведение. Учитываются изменения ширины, загрузка изображений и шрифтов. На мобильном предельная высота — 20 000 логических пикселей; для больших наборов данных используйте страницы или сворачиваемые разделы.

Код веб-виджета

Shadow DOM отделяет разметку и CSS карточки от дашборда, но не является границей безопасности JavaScript. Публикуйте здесь только доверенный код компании: в отличие от iframe обычного сервиса, JavaScript виджета исполняется в контексте страницы. Не используйте parent, top, cookie и внутренние API веб-приложения. Ключи авторизации пользователя и компании в код не передаются; данные получайте через SDK и проверяемый сервером мост.

Обычные HTML/JS и React/JSX поддерживаются. Монтируйте React через createRoot(document.getElementById('root')); поиск элементов через переданный document ограничен своим виджетом, поэтому одинаковые id в разных карточках не конфликтуют. Пишите исполняемый код во вкладке JavaScript, не в inline-обработчиках HTML или <script>. Для фона, текста и элементов используйте тему SDK и CSS-переменные; смена темы обновляет виджет без потери состояния. При скрытии React-корни размонтируются, таймеры и подписки SDK очищаются. Отписывайтесь от собственных внешних подписок в cleanup React-эффектов.

Среда SDK остаётся web: synchra.getRuntime() возвращает web, мобильные действия не запускаются и возвращают признак ignored. В мобильном WebView среда — mobile. Виджеты также поддерживаются в карточках и на экране управления — см. ниже.

Виджеты карточек и управления

В Назначение сервиса кроме обычного сервиса и виджета дашборда доступны:

Назначение Место показа
Виджет задачи В конце карточки задачи, перед комментариями
Виджет инцидента В конце основной карточки инцидента, перед комментариями
Виджет документа В конце карточки документа
Виджет выезда В конце карточки выезда команды
Виджет визита В конце карточки визита
Виджет журнала В конце карточки мероприятия/события журнала
Виджет отчёта После содержания и вложений отчёта
Виджет сотрудника в управлении В конце вкладки «Информация» карточки сотрудника
Виджет экрана управления В вебе под «Ресурсами», в мобильном приложении под основной аналитикой

Без заголовка и отступов. В настройках виджета доступен стандартный свитч с описанием: он скрывает заголовок плашки и убирает внутренние отступы контейнера одновременно в мобильной и веб-версии. Содержимое занимает всю область виджета с выбранной или автоматической высотой; это не полноэкранный режим устройства. Собственные отступы HTML/CSS сервиса сохраняются. Настройка применяется ко всем назначениям виджетов; обычный сервис отображается как прежде. По умолчанию свитч выключен. На мобильном дашборде управление перемещением и видимостью остаётся доступно в режиме редактирования.

Настройка Без заголовка и отступов применяется после сохранения сервиса.

Для одного назначения можно создать несколько сервисов. Они добавляются отдельными плашками в конце карточки, перед комментариями при их наличии. Порядок — по созданию сервисов, от более ранних к новым. Назначение не даёт доступа к карточке: сначала сотрудник открывает разрешённую запись, затем загружаются доступные ему сервисы. Учитываются лицензия Приложения, доступ сервиса, его включение и публикация; на каждой платформе дополнительно проверяется соответствующий переключатель Разрешить в веб-версии или Разрешить в мобильной версии. Виджеты не запускаются в предпросмотре шаблона инцидента. Веб-виджеты с внешним URL не поддерживаются, для них используйте встроенный код. Высоты на мобильном и в вебе настраиваются отдельно, как у виджета дашборда.

Единый контекст записи

Встроенный SDK предоставляет await synchra.getWidgetContext(). В обычном сервисе без карточки результат — null. В виджете возвращается единый объект:

{
  "version": 1,
  "placement": "task",
  "provider_id": "108",
  "entity": { "type": "task", "id": "42" },
  "data": {
    "id": 42,
    "title": "Проверить оборудование",
    "description": "Осмотр перед сменой",
    "status": "in_progress"
  }
}

placement — dashboard, task, incident, document, field_visit, visit, journal, report, control_employee или control. ID компании и записи в общей оболочке всегда строки. Для сотрудника entity.type — employee; для управления и дашборда ID обозначает компанию. В журнале ID относится к мероприятию, а ID журнала доступен в data, когда он есть в карточке.

data содержит выбранные поля отображаемой записи: название, описание, статус, доступные даты, приоритет и ID связанных участников; набор зависит от карточки, отсутствующие поля не создаются искусственно. Контекст управления включает текущие фильтры и статистику, карточки сотрудника — основные данные профиля. Набор полей может отличаться между разделами и платформами; проверяйте наличие поля, не рассчитывайте на обязательный description у всех типов. Пароли, токены, секреты и другие служебные данные авторизации в контекст не включаются. Контекст — данные интерфейса, не доказательство полномочий: для операций сервер обязан отдельно проверять доступ.

Обновления приходят без перезапуска виджета. Подпишитесь на synchra.onWidgetContextChange(callback) и вызовите возвращённую функцию отписки при размонтировании:

import React, { useEffect, useState } from 'react';

function RecordInfo() {
  const [context, setContext] = useState(null);
  useEffect(() => {
    let active = true;
    synchra.getWidgetContext().then(value => { if (active) setContext(value); });
    const unsubscribe = synchra.onWidgetContextChange(setContext);
    return () => { active = false; unsubscribe(); };
  }, []);
  return <p>{context?.data?.description ?? 'Описание не указано'}</p>;
}

Во внешнем мобильном сервисе со старым пакетом SDK можно вызвать synchra.requestPayload('app.widget.context'); синхронное чтение поддерживает window.getSynchraWidgetContext(). При переходе к другой записи экземпляры виджетов создаются заново, чтобы данные разных карточек не смешивались.

Доступные места размещения

Выберите место показа в настройках сервиса из доступных назначений. Разработчику расширения не требуется менять код Synchra24 или подключать компоненты её интерфейса. Для работы с открытой записью используйте getWidgetContext() и проверяйте наличие нужных полей.

Сводки из автоматизаций

Для первой загрузки данных предусмотрите в коде виджета скелетон с той же раскладкой, что у готовой сводки: заголовок, плитки и область графика заранее занимают своё место. Это особенно важно при автоматической высоте. При повторном чтении сохраняйте уже загруженные значения на экране; заменяйте их только после успешного ответа. Скелетон не должен показывать вымышленные нули, а ошибка или отсутствие настроенного источника должны иметь отдельное понятное состояние. Учитывайте системную настройку уменьшения движения.

В веб-дашборде начальный скелетон можно показать до запуска JavaScript. Поместите его разметку во вкладку HTML, стили — во вкладку CSS; отметьте область загрузки role="status" или aria-busy="true". Скелетон, который создаётся только внутри React после запуска кода, не закрывает самый ранний этап загрузки. Дашборд заранее получает доступные сотруднику опубликованные виджеты и их начальную разметку. Это работает как при полном открытии страницы, так и при переходе из другого раздела приложения: скелетон занимает место до первого показа карточки. При временной ошибке обновления списка уже открытая карточка сохраняется; отключение доступа продолжает учитываться. Для виджета без начальной разметки во время загрузки используется заданная высота, затем включается автоматический размер.

Для сводки, которая собирает данные по расписанию, можно установить пакет из виджета и автоматизации. После установки настройте подключение по инструкции в карточке продукта, выполните проверочный и обычный запуск сборщика, затем включите расписание. Проверочный запуск сам по себе не обновляет данные виджета.

Обращайте внимание на время последнего успешного сбора: открытие виджета или кнопка перечитывания не обязательно запускают автоматизацию заново. Недоступные и устаревшие показатели должны быть явно отмечены; отсутствие данных не означает нулевой результат. Сравнение за период появляется только после накопления достаточной истории. Если сводка содержит график, он должен опираться на сохранённые снимки: недостающие периоды нельзя подменять нулями. В основном виде достаточно показателей, периода графика и времени снимка; определения и правила чтения можно вынести в инструкцию карточки продукта. Ошибки, отсутствие и устаревание данных должны оставаться заметными. Поясняйте разрывы сбора в инструкции. При выборе разных показателей обновляйте подписи линий, значения и шкалу; не смешивайте количество событий за период с состоянием на момент снимка.

Доступ к сводке зависит от выбранного способа хранения. При чтении артефактов автоматизаций через SDK сохраняются требования лицензии API и права управления интеграциями. Не расширяйте права обычного сотрудника только ради просмотра такого виджета; заранее проверьте требования продукта в магазине.