Код, библиотеки и SDK

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 и ошибки.