Практические материалы по запуску и развитию

В этом сценарии мы не начинаем с пустого проекта, а берем готовый пример synchra24/app_example, разворачиваем его, подключаем к своей активности в Synchra.24 и проверяем bridge в реальном приложении.

Такой путь подходит, если вам нужно быстро:

• поднять рабочий шаблон внутреннего сервиса;
• проверить, как WebView-приложение общается с мобильным клиентом;
• понять, как устроены API, тема, навигация, выбор пользователей, файлы, камера и другие native-возможности;
• получить отправную точку для своего микроприложения.

Что понадобится

Перед стартом подготовьте:

• установленный Node.js;
• доступ к активности, в которой вы можете создавать внутренние сервисы;
• публичный URL, по которому будет доступно web-приложение;
• смартфон с приложением Synchra.24 для проверки.

Что мы будем использовать

SDK для интеграции

Пакет @synchra24/app — это bridge-SDK для гибридных приложений внутри Synchra.24.

Через него web-приложение получает доступ к:

• разрешенным API-запросам;
• контексту провайдера;
• теме Synchra.24;
• геопозиции;
• выбору пользователей;
• выбору файлов и фото;
• QR-сканеру;
• snackbar, modal и внутренней навигации.

Готовый пример

Репозиторий synchra24/app_example — это рабочий demo-проект, в котором уже подключены основные bridge-методы.

Как Synchra открывает микроприложение

В мобильном приложении внутренний сервис открывается через экран InternalService:

• URL сервиса загружается в WebView;
• сервисный токен передается в ваше приложение;
• bridge проверяет токен перед выполнением native-операций;
• WebView получает тему, контекст провайдера и доступ к разрешенным действиям.

Практически это значит, что ваше приложение остается обычным web-приложением, но запускается внутри контролируемого контейнера Synchra.24.

Шаг 1. Разверните готовый example

Склонируйте репозиторий:

git clone https://github.com/synchra24/app_example.git
cd app_example

Установите зависимости:

npm install

Запустите проект локально:

npm run dev

После этого example будет доступен локально, обычно через Vite dev server.

Если вы хотите просто быстро проверить логику в браузере, этого достаточно. Но для запуска внутри Synchra.24 нужен публичный URL.

Шаг 2. Опубликуйте приложение по публичному URL

Внутренний сервис в активности открывает url, который вы укажете при создании сервиса. Поэтому приложение должно быть доступно извне.

Подойдут любые привычные варианты:

• Vercel;
• свой nginx / static hosting;
• тестовый tunnel для dev-проверки;
• любая публикация собранного фронтенда по HTTPS.

Для production-сборки:

npm run build

На этом шаге итог простой: у вас должен появиться URL, который открывает app_example в браузере.

Шаг 3. Создайте внутренний сервис в активности

Откройте в мобильном приложении настройки нужной активности и перейдите в раздел Сервисы.

В форме создания сервиса заполните:

• Название — как сервис будет называться для пользователей;
• Ссылка — публичный URL опубликованного app_example;
• Иконка — любую подходящую иконку из списка;
• Полномочие — при необходимости, если хотите ограничить доступ отдельным permission;
• Доступно сотрудникам — либо всем, либо только выбранным пользователям.

После сохранения Synchra.24 создаст сервис и выдаст для него service token.

Именно этот токен нужен вашему web-приложению для работы с bridge.

Шаг 4. Подставьте service token в example

Внутри example создается экземпляр клиента:

import { SynchraApp } from '@synchra24/app';

const synchra = new SynchraApp('SERVICE_TOKEN');

Замените SERVICE_TOKEN на токен, который был создан в разделе сервисов активности.

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

Шаг 5. Откройте сервис из активности

Теперь откройте нужную активность в мобильном приложении и перейдите в блок приложений / сервисов.

Выберите созданный сервис. Если все настроено верно:

• откроется ваш app_example внутри Synchra.24;
• isSynchraIntegrated() вернет true;
• приложение сможет вызывать bridge-методы;
• тема и контекст активности будут доступны внутри WebView.

Шаг 6. Проверьте базовую интеграцию

Первый smoke-test лучше сделать на трех вещах:

Проверка интеграции

const integrated = await synchra.isSynchraIntegrated();

Если метод возвращает false, значит:

• приложение открыто не внутри Synchra.24;
• сервисный токен невалиден;
• или у вас открылась обычная web-версия без bridge-контейнера.

Получение контекста провайдера

const provider = await synchra.getProviderContext();

console.log(provider.provider_id);
console.log(provider.profile_id);
console.log(provider.role);

Этот шаг полезен, потому что на нем сразу видно, что приложение запущено именно в нужной активности и получает рабочий контекст пользователя.

Вызов snackbar

await synchra.showSnackbar({
  message: 'Интеграция работает',
  type: 'success',
});

Это простой способ убедиться, что bridge отвечает корректно.

Что уже умеет готовый example

В app_example уже есть примеры вызова основных bridge-методов:

• requestApi
• getProviderContext
• getGeoPosition
• selectUsers
• takePhoto
• pickPhoto
• pickFile
• scanQr
• selectDate
• selectDateRange
• selectTime
• showSnackbar
• openModal
• navigate
• getSynchraTheme
• onSynchraThemeChange

То есть после запуска вы уже получаете не пустой шаблон, а рабочую песочницу для проверки интеграции.

Как подключить сервис к своей активности правильно

Чтобы сервис не выглядел просто как “внешняя ссылка”, обычно стоит сразу продумать:

• кому именно он будет доступен;
• нужен ли отдельный permission;
• должен ли он открываться всем сотрудникам или только части команды;
• должен ли он использовать API активности, документы, задачи, пользователей или файлы.

Если у вас несколько ролей, лучше сразу ограничить доступ так, чтобы сервис видели только нужные сотрудники.

Типовой путь после quick start

Обычно дальше команда идет по такому сценарию:

1. Проверяет app_example как есть.
2. Убеждается, что токен и bridge работают.
3. Меняет интерфейс под свой кейс.
4. Подключает нужные API-запросы через requestApi.
5. Добавляет роли, фильтры, формы и сценарии.
6. Переводит сервис из demo в рабочий внутренний инструмент.

Что можно менять в example в первую очередь

Если вы хотите быстро превратить demo в свой сервис, обычно имеет смысл сначала заменить:

• главный экран;
• названия кнопок и сценариев;
• вызовы demo-методов на реальные API вашей активности;
• тексты и структуру карточек;
• проверку интеграции и стартовый fallback.

Частые причины, почему сервис не работает

Чаще всего проблема одна из этих:

• в сервисе указан неправильный url;
• токен не подставлен в SynchraApp(...);
• опубликована старая версия приложения;
• сервис открыт не внутри Synchra.24, а в обычном браузере;
• нужный bridge-метод требует системных разрешений устройства;
• у пользователя нет доступа к сервису по ролям или permission.

Минимальный результат, который стоит получить

Если вы идете по этому quick start, хорошим первым результатом считается такой сценарий:

• сервис создан в активности;
• example открывается из Synchra.24;
• isSynchraIntegrated() возвращает true;
• getProviderContext() возвращает данные активности;
• showSnackbar() и хотя бы один дополнительный bridge-метод отрабатывают успешно.

После этого у вас уже есть реальная рабочая база для разработки собственного микроприложения внутри Synchra.24.