# Быстрый старт

> Включить функцию, поставить sparku и отправить первое значение на островок.

## 1. Включить функцию

Настройки SparkU → раздел «Интеграции» → внизу блок «Свои интеграции» (бейдж
«ЭКСПЕРИМЕНТ») → «Включить…». Появится предупреждение: функция экспериментальная,
возможно непредвиденное поведение и повышенный расход процессора и батареи. Кнопка
«Включить» не срабатывает по Return — нужно нажать её явно.

После согласия в боковом списке настроек появляется раздел «Свои интеграции» и
открывается мастер новой интеграции.

## 2. Поставить CLI

В том же разделе настроек — строка «sparku» с кнопкой «Установить…». Она кладёт
символическую ссылку `/usr/local/bin/sparku`, указывающую на утилиту внутри
`SparkU.app`. Если `/usr/local/bin` недоступен для записи, macOS один раз спросит
пароль администратора.

Проверить, что команда доступна:

```bash
sparku version
```

## 3. Создать интеграцию мастером

В мастере — пять заготовок: «Задача с прогрессом», «Метрики сервера», «Таймер»,
«Статус сборки», «Список». Каждая уже содержит поля, индикатор, строку и карточку —
остаётся дать название и адрес (slug) или принять предложенный. «Настрою сам»
создаёт пустую интеграцию без полей.

Возьмём заготовку «Статус сборки» с адресом `build`. У неё уже есть поля `stage`
(состояние), `branch` (текст), `started` (время), `link` (ссылка) и кнопка «Открыть»
на карточке.

## 4. Скопировать токен

В редакторе интеграции — раздел «Подключение»: строка `export
SPARKU_TOKEN_BUILD=…` и готовые примеры на curl, Python, Node, Swift. Скопируйте
экспорт и выполните его в терминале, из которого будете тестировать:

```bash
export SPARKU_TOKEN_BUILD=spk_ваш_токен
```

`sparku` сам найдёт эту переменную по адресу интеграции — передавать токен каждый раз
вручную не нужно.

## 5. Первый push

```bash
sparku push build stage=running branch=main started=+0s
```

На островке должен обновиться индикатор и строка плашки. Раскройте островок — увидите
карточку «Статус сборки» с кнопкой «Открыть».

## 6. Проверить, что всё работает

```bash
sparku doctor build
```

Команда по шагам печатает: есть ли сокет, отвечает ли SparkU, найден ли токен,
существует ли интеграция и какие у неё поля. Если что-то не так — `doctor` укажет,
на каком шаге.

## 7. Снять значения

```bash
sparku end build
```

Очищает все значения интеграции — на островке для неё не останется данных (элементы
с видимостью «Пока есть данные» пропадут).

## То же самое через curl

Без CLI, напрямую через UNIX-сокет:

```bash
curl --unix-socket ~/.sparku/run/api.sock \
  -H "Authorization: Bearer $SPARKU_TOKEN_BUILD" \
  -d '{"stage": "running", "branch": "main", "started": "+0s"}' \
  http://sparku/v1/integrations/build/fields
```

Снять значения:

```bash
curl --unix-socket ~/.sparku/run/api.sock -X DELETE \
  -H "Authorization: Bearer $SPARKU_TOKEN_BUILD" \
  http://sparku/v1/integrations/build/fields
```

## Дальше

- [Понятия](/docs/api/ru/concepts.md) — как устроены поля, островок, карточка и токены.
- [Типы полей](/docs/api/ru/fields.md) — что можно присылать в `push` для каждого типа.
- [CLI sparku](/docs/api/ru/cli.md) — все команды и коды выхода.