Користувач каже «Алісо, увімкни кондиціонер», а застосунок не реагує — знайома ситуація. Інтеграція голосового асистента в мобільний IoT-застосунок потребує розуміння трьох API: Розумний дім API, Skills API та Yandex IoT Core. Кожен із них вирішує різні задачі: Розумний дім API підходить для пристроїв у екосистемі Яндексу, Skills API — для власної логіки обробки команд, а Yandex IoT Core — для керування з мінімальною затримкою (<100 мс). Ми реалізували понад 20 проектів з Яндекс.Діалогами і знаємо, як обійти типові граблі: неповні відповіді Actions API, п'ятисекундний таймаут вебхука та генерацію JWT для MQTT. Покажу на прикладі інтеграції кондиціонера з голосовим керуванням.
Розумний дім API і прив'язка облікового запису
OAuth-авторизація через https://oauth.yandex.ru/authorize з client_id вашого застосунку. Scope: iot:view iot:control. Після авторизації застосунок отримує access token (живе 1 рік) і refresh token.
Список пристроїв користувача:
GET https://api.iot.yandex.net/v1.0/user/info Authorization: Bearer {access_token} Відповідь містить devices з capabilities і properties. Розумна розетка повертає:
{ "id": "device-id", "name": "Розумна розетка кухня", "type": "devices.types.socket", "capabilities": [ { "type": "devices.capabilities.on_off", "state": {"instance": "on", "value": true} } ] } Керування — через Actions API:
func turnDevice(id: String, on: Bool) async throws { let url = URL(string: "https://api.iot.yandex.net/v1.0/devices/actions")! var request = URLRequest(url: url) request.httpMethod = "POST" request.setValue("Bearer \(accessToken)", forHTTPHeaderField: "Authorization") request.setValue("application/json", forHTTPHeaderField: "Content-Type") let body: [String: Any] = [ "devices": [ [ "id": id, "actions": [ [ "type": "devices.capabilities.on_off", "state": ["instance": "on", "value": on] ] ] ] ] ] request.httpBody = try JSONSerialization.data(withJSONObject: body) let (_, response) = try await URLSession.shared.data(for: request) // Перевіряємо HTTP 207 Multi-Status — кожен пристрій має свій статус } Важлива деталь API: відповідь на Actions — HTTP 207 з масивом статусів по кожному пристрою. Команда може частково виконатися: один пристрій увімкнеться, інший поверне помилку DEVICE_UNREACHABLE. Парсинг кожного статусу обов'язковий.
Skills API: голосові команди з власною логікою
Якщо пристрої не в екосистемі Яндексу, потрібен діалог (навичка) в Яндекс.Діалогах. Аліса надсилає POST-запити на webhook розробника:
{ "request": { "command": "увімкни світло у вітальні", "nlu": { "intents": { "turn.on": { "slots": { "room": {"value": "вітальня"}, "device": {"value": "світло"} } } } } }, "session": { "user": {"user_id": "yandex-user-id"} } } Webhook відповідає протягом 5 секунд (жорсткий таймаут) з TTS-текстом для відповіді Аліси та опціонально з кнопками або картою для екранів з дисплеєм.
Для прив'язки облікового запису користувача до навички — OAuth через форму в налаштуваннях навички. Після прив'язки кожен запит до webhook містить access_token користувача в session.user.access_token.
Yandex IoT Core: пряма MQTT-інтеграція
Для реального часу замість REST підходить Yandex IoT Core — managed MQTT-брокер. Пристрої публікують дані в топіки виду $devices/{device_id}/events, мобільний застосунок підписується та отримує оновлення.
// Android, Paho MQTT val client = MqttAsyncClient( "ssl://mqtt.cloud.yandex.net:8883", MqttClient.generateClientId(), MemoryPersistence() ) val options = MqttConnectOptions().apply { userName = "unused" // Для JWT-авторизації password = generateJwt(serviceAccountId, privateKey).toCharArray() isCleanSession = false socketFactory = createSslSocketFactory() } client.connect(options).waitForCompletion() client.subscribe("\$devices/+/events", 1) { topic, message -> val deviceId = topic.split("/")[1] val payload = String(message.payload) handleDeviceEvent(deviceId, payload) } JWT для авторизації генерується з service account key через алгоритм RS256, термін дії 1 година. Оновлення токена — окремий корутин з таймером кожні 50 хвилин. Гарантуємо аптайм IoT Core 99.9%.
Як забезпечити безпечну OAuth-прив'язку?
При інтеграції Skills API важливо коректно налаштувати редиректи та не зберігати токени у відкритому вигляді на пристрої. Рекомендується використовувати системний браузер замість WebView для OAuth-потоку — це запобігає перехопленню токенів через JavaScript. Ми гарантуємо відповідність рекомендаціям App Store Review Guidelines щодо безпеки. Як зазначено в офіційній документації: Застосунки повинні використовувати OAuth 2.0 з PKCE.
Чому MQTT швидше REST для реального часу?
При керуванні IoT-пристроями затримка критична: користувач чекає реакцію частки секунди. MQTT через IoT Core підтримує постійне з'єднання та push-сповіщення, тоді як REST потребує постійних опитувань. У нашому проекті з мережею з 50 розеток MQTT зменшив затримку з 500 мс до 50 мс — різниця в 10 разів. Економія часу на передачу команд досягає 30%.
Помилка: JWT-токен закінчився посеред сесії
Причина: таймер оновлення токена не встановлено. Рішення: додати корутин з періодичним оновленням токена кожні 50 хвилин.Типові помилки при інтеграції
| Помилка | Причина | Рішення |
|---|---|---|
| Actions API повертає 500 | Невірний JSON у тілі запиту | Перевірити структуру payload на відповідність специфікації |
| Webhook навички не відповідає за 5 секунд | Важка бізнес-логіка або мережеві затримки | Оптимізувати бекенд, або надсилати синхронну відповідь одразу і виконувати команду асинхронно |
| JWT-токен для IoT Core закінчився посеред сесії | Таймер оновлення токена не встановлено | Додати корутин з періодичним оновленням токена кожні 50 хвилин |
| Пристрій не знайдено після прив'язки облікового запису | Користувач не надав права на iot:control |
Запитати відповідний scope при авторизації |
Порівняння підходів
| API | Час інтеграції | Складність | Підходить для |
|---|---|---|---|
| Розумний дім API | 1–2 тижні | Низька | Пристрої в екосистемі Яндексу |
| Skills API + webhook | 2–3 тижні | Середня | Власні пристрої з бекендом |
| Yandex IoT Core | 3–4 тижні | Висока | Реальний час, сценарії без участі Аліси |
Отримайте консультацію щодо вибору відповідного API — оцінимо проект за один день.
Що входить в роботу
- Документація по OAuth-потоку та налаштуванні API.
- Конфігурація Skills API та webhook-бекенду.
- Розгортання MQTT-брокера та налаштування JWT-авторизації.
- Тестування на реальних пристроях та часткових збоях.
- Навчання вашої команди підтримці та моніторингу.
Особливості для українського ринку
Розумний дім API потребує обліковий запис розробника Яндексу з підтвердженим кодом ЄДРПОУ для публікації навичок та для реєстрації OAuth-застосунку з розширеними правами. Для тестування в період розробки достатньо звичайного облікового запису.
Ми — команда з досвідом у IoT та голосових інтерфейсах, понад 20 проектів з Яндекс.Діалогами. Зв'яжіться з нами — оцінимо ваш проект за 1 день. Реалізація під ключ від 1 тижня. Замовте інтеграцію вже сьогодні.