Synchra.24
menu_bookDocumentation
Practical guides for setup and development

Find guides for getting started, building workflows and adding your own tools to your company workspace.

folderEmbedded services

Importing and exporting ZIP templates

Local ZIP templates: format, settings, restrictions, import and export.

Translation is currently unavailable. The original is shown.

В веб-версии откройте Администратор → Сервисы → Новый сервис → Из ZIP-шаблона. Выберите архив. Приложение проверит его и покажет идентификатор и версию шаблона, название, назначение, высоты виджета, полномочие и доступ в веб-версии. Название можно изменить перед созданием. Нужны лицензия Приложения, доступ к панели администратора и право admin_edit_provider_services; AI-лицензия не требуется.

Кнопка Создать сервис создаёт отдельный встроенный сервис с новым токеном и черновиком v1. Старые сервисы не заменяются, даже если имя или идентификатор шаблона совпадают. Исходники открываются на вкладке HTML, без автоматического выполнения кода. Проверьте код и настройки, при необходимости используйте предпросмотр и отдельно нажмите Опубликовать. Сотрудники выбираются заново в настройках доступа. События, артефакты и секретные переменные не создаются при импорте.

Формат пакета, версия 1

service.json
index.html
style.css
script.js

Допускается одна общая папка, например my-service/service.json. Пути в files считаются относительно папки конфигурации и могут содержать вложенные каталоги. Конфигурация должна быть ровно одна.

{
  "format": "synchra.service-template",
  "schema_version": 1,
  "template": {
    "id": "com.example.stock",
    "version": "1.0.0",
    "description": "Компактный виджет склада"
  },
  "service": {
    "name": "Склад",
    "icon": "msInventory_2",
    "permission": "warehouse_view",
    "web_enabled": true,
    "purpose": "dashboard_widget",
    "widget_height_mobile": 100,
    "widget_height_web": 280,
    "widget_full_bleed": false
  },
  "files": {
    "html": "index.html",
    "css": "style.css",
    "js": "script.js"
  }
}
  • format и schema_version определяют формат пакета, а template.id и template.version — идентичность и версию самого шаблона. Это разные версии. Экспорт редактора создаёт локальный идентификатор local.service и версию 1.0.0; перед распространением задайте собственный идентификатор и версию. Повторный импорт всегда создаёт копию, без автоматического обновления установленных сервисов.
  • template.id: 3–128 строчных латинских букв, цифр, точек, _, -, начинается с буквы. Версия имеет вид 1.0.0, допускается суффикс, например 1.0.0-beta.1. Описание необязательно, до 2000 символов.
  • service.name обязателен, 2–100 символов и до 200 байт UTF-8. Остальные настройки необязательны: иконка по умолчанию msWebAsset, полномочие пустое, веб-доступ выключен, назначение service, обе высоты 0 (стандартные значения), widget_full_bleed: false (с заголовком и отступами), widget_auto_height: false (высота вручную). Необязательное поле widget_auto_height принимает true или false: при true размер виджета определяется содержимым на обеих платформах, а ручные высоты сохраняются для возврата к прежнему режиму. Настройка переносится при импорте, экспорте и установке из магазина. Поле widget_full_bleed необязательно, принимает только true или false и сохраняется при экспорте и импорте ZIP-шаблона. Допустимы все поддерживаемые назначения виджетов и стандартные ограничения высот, описанные выше.
  • Иконка должна быть из общего списка приложения. Полномочие — строчные латинские буквы и _. Нельзя переносить token, provider_id, allowed_users, флаги публикации и другие поля установленного сервиса: неизвестные поля конфигурации отклоняются.
  • files.html, files.css, files.js обязательны и указывают на разные файлы UTF-8. Для HTML подходят .html/.htm, для CSS .css, для JavaScript .js/.jsx/.mjs. Сам HTML — фрагмент body, как в редакторе. JSX сохраняется без предварительного преобразования, React и SDK предоставляет движок.

Ограничения и ошибки

ZIP до 6 МиБ, исходники до 5 МиБ сериализованного JSON, конфигурация до 64 КиБ. Всего до 32 записей вместе с каталогами, суммарный заявленный распакованный размер до 5 МиБ + 192 КиБ. Кроме четырёх основных файлов допускаются README.md, LICENSE и LICENSE.txt рядом с конфигурацией. Служебные .DS_Store и записи __MACOSX/ игнорируются, но учитываются в общих ограничениях размера и числа записей. Вложенные изображения, произвольные ресурсы и npm-пакеты пока не импортируются; изображения можно включить как data:.

Поддерживается обычный ZIP с STORE/DEFLATE, без пароля, ZIP64, нескольких томов и символических ссылок. Пути — относительные, латиницей, без .., обратных слешей и абсолютных адресов. Дублирующиеся имена, включая различия только регистром, отклоняются. Для кода и конфигурации проверяются UTF-8, фактический размер и CRC; распаковка ограничена даже при неверном размере в каталоге ZIP. Сервер повторяет проверку исходного архива и проверяет права до распаковки. При ошибке проверки сервис не создаётся.

Старый ZIP только с тремя исходниками не считается шаблоном. Распакуйте его и используйте прежнюю Загрузку кода из файлов, либо добавьте service.json по формату выше. Импорт не запускает код; выполнение происходит только при последующем явном предпросмотре или использовании опубликованного сервиса.

Локальные шаблоны и магазин

ZIP-шаблон создаёт отдельную копию сервиса без связи с обновлениями продавца. Магазин устанавливает проверенную версию продукта и поддерживает последующие обновления. При импорте локального архива сервис нужно проверять и настраивать самостоятельно.

Для переноса выберите ZIP-файл в окне импорта, проверьте сведения о шаблоне и нажмите Создать сервис. Если архив не подходит, система покажет причину; новый сервис при этом не создаётся.