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

Code, libraries, and SDK

JavaScript and React, embedded libraries, bridge, theme, and working with artifacts.

Translation is currently unavailable. The original is shown.

React и JSX

React и ReactDOM входят в веб-версию и доступны в предпросмотре и опубликованном сервисе. Новый сервис содержит React-пример с чтением артефакта. В HTML укажите контейнер:

<div id="root"></div>

Во вкладке JavaScript можно писать JSX, функциональные компоненты и хуки:

import React, { useState } from 'react';
import { createRoot } from 'react-dom/client';

function App() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>Нажатий: {count}</button>;
}

createRoot(document.getElementById('root')).render(<App />);

Допустимы импорты из react, react-dom/client, lodash и dayjs, а также глобальные React и ReactDOM. Явно вызывайте createRoot(...).render(...): компонент не монтируется автоматически. synchra.getArtifact() работает из обработчиков и эффектов; отображайте загрузку и обрабатывайте ошибки. Другие сторонние модули и TypeScript не поддерживаются; в sandbox обычного сервиса также недоступны CDN и прямые сетевые запросы. Обычный сервис выполняется в sandbox без доступа к авторизации основного сайта. Для веб-виджета действует описанная выше модель доверенного кода в Shadow DOM. В лимит 5 МиБ входят исходники сервиса; встроенные React, Lodash, Day.js и SDK не учитываются.

Кнопка форматирования работает с JSX. Ошибки подготовки кода показываются в панели логов; исходник остаётся в редакторе. Обычные сервисы на JavaScript продолжают работать.

Кнопка ⓘ в верхней панели рядом с AI-помощником и обновлением открывает README библиотеки @synchra24/app с GitHub и дополнение о событиях веб-моста в окне документации. Полное руководство по событиям приведено ниже и в разделе Запуск по событиям. Заголовки, списки, таблицы и примеры кода отображаются в формате Markdown. Можно открыть оригинал на GitHub; при ошибке доступна повторная загрузка.

Lodash и Day.js

Библиотеки встроены в движок: доступны без CDN и установки пакетов в предпросмотре и опубликованном сервисе. Можно использовать глобальные _ и dayjs либо импорты:

import _ from 'lodash';
import debounce from 'lodash/debounce';
import dayjs from 'dayjs';

const groups = _.groupBy(items, 'status');
const date = dayjs('13.10.2026', 'DD.MM.YYYY', true);
if (date.isValid()) console.log(date.format('DD.MM.YYYY'));
const moscowTime = dayjs.utc('2026-10-13T09:00:00Z').tz('Europe/Moscow');

Day.js использует русскую локаль по умолчанию; английская также встроена (dayjs.locale('en') или dayjs(value).locale('en')). Следующие плагины уже подключены через dayjs.extend, повторная настройка не нужна:

Плагины Возможности
utc, timezone UTC и явное преобразование часовых поясов
customParseFormat, localizedFormat Разбор заданного формата, строгая проверка и локализованный вывод дат
relativeTime, duration Относительное время и длительности
isBetween, isSameOrBefore, isSameOrAfter, minMax Диапазоны, сравнение, минимальная и максимальная дата
isoWeek Недели по ISO

Импорты dayjs/plugin/<name> разрешены для перечисленных плагинов, локали — dayjs/locale/ru и dayjs/locale/en. Для lodash доступны основной модуль и методы через lodash/<method>. Не используйте неуказанные плагины или другие локали: они не входят в движок. Часовой пояс задавайте явно по сценарию сервиса; время браузера может отличаться от времени компании.

Проверка моста и ключ сервиса

При старте проверяйте await synchra.isSynchraIntegrated() перед запросами контекста, артефактов и другими действиями через мост. До завершения проверки кнопки таких действий должны быть отключены. При false покажите сообщение о недоступном мосте и не выполняйте запросы: SDK возвращает false также при отклонённом ключе сервиса.

Движок автоматически передаёт SERVICE_TOKEN — ключ текущего сервиса — и создаёт synchra как new SynchraApp(SERVICE_TOKEN). Используйте готовый экземпляр. Не прописывайте реальный ключ в исходниках, не выводите его в логи и не заменяйте токеном пользователя или компании. Для внешнего приложения по URL ключ указывается при создании экземпляра SDK согласно документации библиотеки; для встроенного сервиса это уже делает движок.

const integrated = await synchra.isSynchraIntegrated();
if (!integrated) {
  // Покажите сообщение и оставьте действия моста отключёнными.
  return;
}
const artifact = await synchra.getArtifact('warehouse.stock');
// Отобразите artifact.value с обработкой загрузки, пустых данных и ошибок.

Пример выше — тело асинхронной функции. Стартовый React-шаблон проверяет мост в useEffect, хранит результат проверки и разрешает загрузку только при true. Эти же правила входят в инструкции AI-помощнику.

Предпросмотр эмулирует мост, передаёт тестовый ключ preview-service и возвращает успешный результат проверки для него. Проверка ключа выполняется при каждом вызове. Чтение артефактов возвращает только содержимое вкладки «Тестовые артефакты». Тестовый ключ не предоставляет доступ к реальным данным компании. Специально отключать проверку интеграции для предпросмотра не нужно.

Цвета и типографика

После успешной проверки интеграции читайте synchra.getSynchraTheme(): синхронный метод возвращает {active, current, themes} или null. Имена полей одинаковы на обеих платформах: primary, secondary, text, title, elements, inputGrey, border, controlPrimary, error, success, button, buttonText, white. Цвета берите из current активной темы — светлой или тёмной. В мобильном приложении это палитра мобильной версии, в браузере — цвета окружающего веб-интерфейса, включая полупрозрачные панели, поля, границы и акцент. Один и тот же код сервиса работает без отдельного выбора палитры; среду при необходимости определяйте через synchra.getRuntime(). Изменения отслеживайте через synchra.onSynchraThemeChange(callback). Возвращённую функцию отписки вызывайте при размонтировании. Обновляйте CSS-переменные без перезагрузки сервиса.

Мобильная палитра для справки (не фиксируйте эти значения в коде веб-сервиса):

Роль Ключ темы Светлая / тёмная
Фон primary #e5e5e5 / #212529
Панели secondary #eeeeee / #343a40
Текст text #242424 / #adb5bd
Заголовки title #3a3a3a / #adb5bd
Иконки, вторичный текст elements #50565c / #adb5bd
Поля inputGrey #d7d7d7bf / #343a40
Границы border #d4d4d4 / #131517ff
Акцент controlPrimary #ffb703
Ошибка / успех error / success #f94144 / #52b788

На жёлтых кнопках используйте тёмный текст #242424 в обеих темах. buttonText относится к нейтральным кнопкам. Веб-версия и веб-предпросмотр передают актуальные CSS-цвета веб-интерфейса под теми же ключами; мобильный предпросмотр сохраняет мобильную палитру. В themes находятся базовые палитры текущей платформы, а активная обновляется вычисленными цветами интерфейса. Для текущего оформления всегда используйте current: значения могут быть rgba(...), а веб-акцент может отличаться от мобильного жёлтого. Смена темы и акцента вызывает событие SDK и обновляет стандартные CSS-переменные без перезапуска сервиса и потери его состояния. Это работает в обычных сервисах, виджетах Shadow DOM и подключённых по URL сервисах с поддержкой моста. Цвета сервиса, прописанные вручную вместо обращения к SDK, автоматически не заменяются.

Рекомендуемые размеры/межстрочные интервалы в CSS-пикселях: основной текст 14/19, подписи 12/16, заголовки карточек 17/22 или 19/28, заголовок страницы 25/31. Для полей на iPhone используйте 16px, для зон нажатия — минимум 44px. Текст обычный 400, выделенный 500–700, заголовки 700–800. В мобильном приложении используются Google Sans и Manrope; в WebView эти шрифты автоматически не наследуются, поэтому задавайте системный запасной шрифт, не подключая CDN. Эти правила включены в инструкции AI-помощнику и стартовый шаблон новых сервисов. Существующие публикации автоматически не переписываются.

Запись артефактов из встроенного сервиса

После проверки интеграции вызовите await synchra.setArtifact('service.settings', {enabled: true}). Имя должно уже существовать в этой компании; метод заменяет JSON целиком, возвращает обновлённую версию и не создаёт отсутствующий артефакт. Нужны лицензия API и admin_edit_provider_integrations; максимум 1 МиБ на значение. Веб-сервисы, Shadow DOM-виджеты и обновлённый мобильный мост используют одинаковое событие app.automation.artifact.set. В старом внешнем SDK используйте requestPayload с {name, value}. В предпросмотре изменяются только тестовые данные до перезапуска.

Для чтения этих данных во всех этапах автоматизации подключите верхний блок artifacts; transform получает context.artifacts. Запись сама по себе не запускает автоматизацию. Примеры, API и ошибки.