X2Chat Mini Apps

Подключите своё веб-приложение к мессенджеру X2Chat. Мини-апп открывается во встроенном WebView, получает бесшовный вход по аккаунту пользователя, может запрашивать данные через защищённый Host API и отправлять карточки-ссылки в чат.

1. Что такое мини-апп

Мини-апп — это размещённый по HTTPS веб-фронтенд (HTML/JS/CSS, любой стек). X2Chat хранит о нём запись в реестре (slug, name, icon_url, launch_url, allowed_origins, available_scopes) и открывает launch_url во WebView. Приложение может быть полностью самостоятельным (свой бэкенд, своя БД, свой бренд) — X2Chat выступает «лаунчером» и поставщиком идентичности пользователя.

2. Быстрый старт — самостоятельная регистрация

Подключение полностью self-service: размещаете манифест на своём домене и шлёте одну заявку. Подключать вас вручную никто не должен.

1. Разместите фронтенд по HTTPS (свой домен) — либо попросите проксировать под путём https://ru.x2chat.com/apps/<slug>/ (см. §8).
2. Положите манифест и иконку рядом с приложением (см. ниже).
3. Отправьте одну заявку POST /api/v1/mini-apps/register из своего аккаунта X2Chat.
4. Готово: без запрошенных прав — приложение в каталоге сразу; с доступом к данным — после одобрения (1 клик оператора).

2.1. Манифест

Файл x2chat-manifest.json в корне приложения (на том же домене, что и launch_url — это и есть подтверждение, что приложение ваше):

{
  "slug": "otc",
  "name": "OTC Desk",
  "description": "OTC-сделки и котировки",
  "launch_url": "https://ru.x2chat.com/apps/otc/",
  "scopes": ["profile:read"]
}

Иконку положите рядом — icon.png (см. §9), отдельно указывать не нужно.

2.2. Регистрация — одна команда

Из аккаунта X2Chat (нужен ваш токен авторизации; запрос идёт от вас — вы становитесь владельцем приложения):

curl -X POST https://ru.x2chat.com/api/v1/mini-apps/register \
  -H "Authorization: Bearer <ВАШ_ТОКЕН_X2CHAT>" \
  -H "Content-Type: application/json" \
  -d '{"manifest_url":"https://ru.x2chat.com/apps/otc/x2chat-manifest.json"}'

Запись создаётся на обоих дата-центрах автоматически. Обновить приложение (имя/иконку/права) — поменяйте манифест и повторите ту же команду.

3. JavaScript-мост (WebView ↔ X2Chat)

После загрузки страницы X2Chat инжектит window.X2Chat.launch и шлёт событие x2chat:ready:

window.addEventListener('x2chat:ready', (e) => {
  const { sessionToken, context } = window.X2Chat.launch;
  // context = { app_id, slug, user_id, slot_id, chat_id, scopes, theme, locale }
  // slot_id — crypto-идентификатор юзера (null для обычных аккаунтов)
  applyTheme(context.theme);     // напр. 'blue'
  applyLocale(context.locale);   // напр. 'ru'
});

Если событие уже прошло к моменту подписки — проверьте наличие window.X2Chat?.launch напрямую.

Методы моста

3.1. Pull-to-refresh — постраничное обновление

Когда пользователь тянет контейнер мини-аппа вниз (на вершине прокрутки), X2Chat не перезагружает весь WebView — это выкидывало бы из SPA и сбрасывало навигацию. Вместо этого хост шлёт в страницу событие x2chat:refresh, а мини-апп сам обновляет свою ТЕКУЩУЮ страницу и подтверждает это.

window.addEventListener('x2chat:refresh', async () => {
  try {
    await refreshCurrentPage();      // ваш re-fetch/re-render активного экрана
  } finally {
    // ОБЯЗАТЕЛЬНО: иначе через 2 с хост перезагрузит весь WebView (fallback)
    window.X2Chat?.postMessage?.({ method: '_refreshHandled' });
  }
});

3.2. «Назад» — навигация по иерархии

Кнопка/жест «назад» по умолчанию закрывает мини-апп. Чтобы «назад» сначала ходил по внутренней иерархии мини-аппа (деталь → список → корень) и закрывал его только с корневого экрана, мини-апп сообщает хосту своё навигационное состояние при каждой смене экрана:

function syncNav() { window.x2.setBackState(router.canGoBack(), hasUnsavedChanges()); }
// вызывать syncNav() на каждой смене экрана и на x2chat:ready

window.addEventListener('x2chat:back', () => { router.back(); syncNav(); });

window.addEventListener('x2chat:exitRequest', () => {
  if (confirm('Выйти из приложения?')) window.X2Chat.postMessage({ method: 'close' });
});

3.3. Камера и микрофон (getUserMedia)

Камера и микрофон внутри мини-аппа работают через стандартный navigator.mediaDevices.getUserMedia — отдельный мост не нужен. X2Chat выдаёт WebView веб-разрешение на медиа автоматически. Типичный сценарий — сканер QR внутри приложения.

// задняя камера для сканера
const stream = await navigator.mediaDevices.getUserMedia({
  video: { facingMode: { ideal: 'environment' } }, audio: false
});
videoEl.srcObject = stream; await videoEl.play();
// декодировать QR любой библиотекой: @zxing/browser | html5-qrcode | jsQR
stream.getTracks().forEach(t => t.stop());   // по завершении — ОБЯЗАТЕЛЬНО погасить

3.4. Поделиться и выбор контакта

Для крипто-кошельков и приложений, которым нужна идентичность собеседника или системное «поделиться» — через window.x2.requestCapability(scope, payload):

// поделиться системно
await window.x2.requestCapability('share:external', { text: 'TRC20 адрес', url: 'https://…' });

// выбрать получателя (нужен scope contacts:pick)
const c = await window.x2.requestCapability('contacts:pick', {});
if (!c.cancelled && c.slot_id) resolveAndSend(c.slot_id, c.display_name);

3.5. Уведомить получателя по slot_id (message:notify)

Хост резолвит/создаёт 1:1-чат с получателем по slot_id и отправляет ему E2E-сообщение text. Пуш приходит штатно — как на любое новое сообщение, отдельный notify слать не нужно. Тело сообщения = текст пуша. Главный сценарий — кошелёк, уведомляющий получателя перевода.

const r = await window.x2.requestCapability('message:notify', {
  to:   { slot_id: 'YQS4C0' },   // получатель по slot_id (из contacts:pick / формы)
  text: '💸 Перевод 2 USDT'       // тело сообщения = текст пуша
});
// → { success: true, chat_id, message_id }
// → { success: false, error: 'recipient_not_found' | 'no_permission' | 'empty_text' }

3.6. Управление сессией (token-broker)

Launch-сессия мини-аппа короткоживущая (30 мин). Контейнер X2Chat работает как token-broker: при истечении токена (host-API вернул 401) или по запросу контейнер сам переиздаёт сессию через настоящую авторизацию пользователя, ре-инжектит свежий window.X2Chat.launch.sessionToken и шлёт событие. Перелогиниваться или перезапускать приложение не нужно — вызовы переживают истечение прозрачно (контейнер делает авто-retry один раз).

// форсировать переиздание проактивно (не дожидаясь 401)
const r = await window.x2.requestCapability('session:refresh', {});
// → { success: true, sessionToken }

// хост шлёт событие после успешного переиздания;
// к этому моменту window.X2Chat.launch.sessionToken уже свежий
window.addEventListener('x2chat:session', (e) => {
  if (e.detail.state === 'active') { /* токен обновлён */ }
});

4. Права (scopes)

При установке пользователь соглашается с подмножеством available_scopes; в launch-сессию попадают только выданные granted_scopes.

5. Бесшовный вход (SSO)

Самостоятельное приложение может логинить пользователя без отдельного входа, доверившись X2Chat-сессии:

1. Фронт берёт window.X2Chat.launch.sessionToken и отправляет его на свой бэкенд вместе с window.location.origin (JWT на клиенте не валидируем).
2. Бэкенд по origin выбирает дата-центр и делает server-to-server запрос:

GET  <X2CHAT_HOST_API>/api/v1/mini-apps/host/me
Header: X-X2Chat-Mini-App-Session: <sessionToken>

→ { success, profile: { id, email, username, display_name, avatar_url, language, theme } }
  401 — токен невалиден / истёк / чужой ДЦ
  403 — не выдан scope profile:read

По стабильному profile.id заведите/найдите своего пользователя и выдайте свою сессию. Токен X2Chat живёт ~5 минут и больше не нужен.

6. «Поделиться» в чат (карточка + ссылка)

Отдельного метода «вложить картинку» нет — используйте превью ссылок (OpenGraph):

1. Отдавайте публичную (по неугадываемому токену) страницу с OG-тегами: og:title, og:description, og:image (абсолютный URL), og:site_name.
2. Положите ссылку в чат черновиком:

window.X2Chat.postMessage({
  method: 'sendMessageDraft',
  payload: { text: 'Подпись\nhttps://ru.x2chat.com/apps/<slug>/s/<token>' }
});

Клиент X2Chat сам анфёрлит ссылку и рисует карточку с картинкой. Превью фетчит устройство каждого получателя (User-Agent X2Chat/LinkPreview, таймаут 5 с, кэш 6 ч) — поэтому страница и картинка должны быть публично доступны. Рекомендуемая картинка: PNG/JPEG, ~1.91:1.

7. Host API

Базовый путь: /api/v1/mini-apps/host. Заголовок сессии: X-X2Chat-Mini-App-Session: <JWT>.

7a. Server-to-server notify (push офлайн-получателю)

Серверный бэкенд приложения может отправить получателю системный push (работает офлайн). Аутентификация — app-key (выдаёт платформа), не launch-сессия.

POST <X2CHAT_HOST_API>/api/v1/mini-apps/host/notify
Headers: X-X2Chat-App-Key: <секрет>
Body: { "to": {"user_id"|"slot_id"}, "push": {"title","body"},
        "deeplink"?: "https://… (только https/x2chat)", "dedup_key"?: "…" }
→ { "success": true, "pushed": true, "deduped": false }

• Push через FCM/APNS/HMS/Mi; уважает настройки уведомлений и «Не беспокоить».
• Анти-спам: лимит на получателя (6/час) + общий лимит ключа + дедуп по dedup_key.
• App-key хранится хешированным (sha256) + привязан к IP-allowlist. Запросить — у оператора.
• Коды: 401 невалидный ключ · 403 нет права/IP · 429 лимит.

8. Хостинг под под-путём (без своего домена)

Приложение можно проксировать под путём на доменах X2Chat: https://ru.x2chat.com/apps/<slug>/ и https://ix.x2chat.com/apps/<slug>/.

• Фронт обязан ходить относительными путями (fetch('api/...'), src="static/..." — без ведущего /). Абсолютный /api/... ушёл бы на API самого X2Chat.
• launch_url — со слешем на конце; добавьте редирект /apps/<slug> → /apps/<slug>/.
• Реестр mini_apps не реплицируется между ДЦ — регистрируйтесь на каждом ДЦ со своим launch_url.

9. Иконка — автоподтягивание из приложения

Каталог мини-аппов в клиенте — сетка иконок. Иконку поставляет само приложение по соглашению (как favicon) — никуда отдельно загружать не нужно.

launch_url:  https://ru.x2chat.com/apps/otc/
иконка:      https://ru.x2chat.com/apps/otc/icon.png

launch_url:  https://cdn.example.com/app/index.html
иконка:      https://cdn.example.com/app/icon.png

X2Chat подтянет её автоматически (icon_url вычисляется из launch_url). Клиент грузит иконку вживую — заменили файл, иконка обновилась без переустановки. Требования: квадрат, ≥ 256×256, PNG. Нет файла (404) → показывается градиент с первой буквой названия. name держите коротким (2 строки под иконкой).

10. Частые ошибки