Уебхукове и API - BoothDock Wiki

BoothDock Studio може да уведомява други програми за всяка стъпка от сесията (Уебхукове) и само да бъде управлявано от други програми (локален API). И двете намираш в административния панел под Система → Автоматизация.

В BoothDock Studio 1.4.0 и по-старите версии уебхуковете там все още се наричат „Тригери“.

Уебхукове и експорт в реално време има само под Windows. Локалният API е наличен от версия 1.4.0 и на iPad и iPhone.

Типични приложения: осветление или DMX в синхрон с обратното броене, overlay за стрийм, брояч на входа – или Stream Deck като дистанционно управление за бокса.

Система → Автоматизация: експорт в реално време, уебхукове и локален API

Настройка на уебхукове

Въведи Програма, Адрес (URL) или и двете. При всяко събитие боксът извиква и двете:

Програма – файл .exe, .bat или .cmd. Извикване: програма <събитие> <param1> <param2> …. Всяка стойност пристига като отделен аргумент, дори ако съдържа интервали. Програмата се стартира без прозорец, в собствената си папка. PowerShell скрипт (.ps1) стартираш чрез малък .bat пред него.
Адрес (URL) – http или https, извикван чрез GET: https://твоят-сървър/hook?event_type=<събитие>&param1=…&param2=…. Стойностите са URL-кодирани; параметрите, които вече са в адреса ти, се запазват.

Сесията никога не чака уебхука ти: програмата и извикването вървят паралелно, а едно извикване може да трае най-много 5 секунди. Изпрати тест веднага изпраща session_start – така проверяваш връзката, без да стартираш сесия.

Програмата и адресът се настройват само директно на бокса, не през Hub: пътят до програма е право да се изпълни нещо на компютъра.

Събития

Събитие	Кога	Параметри
`session_start`	Гост стартира сесия, режимът е определен	1: режим (`PrintOnly`, `PrintAndGIF`, `OnlyGIF`, `SlowMoOr360`, `Video`), 2: режим на BoothDock (`photo`, `gif`, `boomerang`, `video`, `slowmo`, `ai`)
`countdown_start`	Обратното броене започва	1: секунди
`countdown`	Всяка секунда от обратното броене	1: напредък в проценти (от 0)
`capture_start`	Обратното броене приключи, заснемането започва	–
`file_download`	Камерата е записала снимка	1: име на файла, 2: пълен път
`processing_start`	Обработката започва	по едно име на файл за всеки оригинал от камерата, като последна стойност файлът за печат (засега празен)
`sharing_screen`	Появява се екранът с резултата (веднъж на сесия)	–
`printing`	Лист се изпраща към принтер	1: файл (засега празен), 2: копия, 3: принтер
`file_upload`	Файл е пристигнал в Hub (за всеки файл)	1: път на бокса, 2: линк към галерията, 3: тип (`print`, `photo`, `original`, `animation`, `boomerang`, `video`), 4: албум (име на събитието)
`session_end`	Сесията приключва – завършена, прекъсната, изтекла или изтрита	–

Пример за .bat, който записва всяко събитие: echo %DATE% %TIME% %* >> "%~dp0events.log"

Локален API

Други програми управляват бокса чрез HTTP – например Stream Deck, собствен скрипт или управление на 360° от телефона.

Включване: Система → Автоматизация → Включи API. Фабрично API е изключен. Порт 1500, може да се промени.
Адрес: http://localhost:1500/api/<команда> (или 127.0.0.1). Фабрично боксът приема заявки само от този компютър.
Парола: 16 знака, показва се в същия раздел – копирай я или генерирай нова. Подава се като ?password=…, като заглавка X-Api-Password или като Authorization: Bearer …. Само ping работи без нея.
Отговор: винаги HTTP 200 с JSON, например {"ApiVersion":1,"Command":"cancel","IsSuccessful":true,"ErrorMessage":""}. Дали е успешно, пише в IsSuccessful, а причината при грешка – в ErrorMessage. Някои команди връщат и Data.

Пълно извикване: http://localhost:1500/api/start?mode=print&password=ТВОЯТА-ПАРОЛА

Управление от мрежата (телефон, таблет, 360°)

Включи допълнително Достъпно и от мрежата. Тогава боксът приема заявки от устройства в същата Wi-Fi/LAN мрежа – никога от интернет.

Адрес за телефона: показва се в реда за състояние, например http://192.168.1.20:1500. Примерът под него тогава веднага показва подходящия адрес.
Без въвеждане на IP: Боксът сам се обявява в мрежата (mDNS/Bonjour, тип услуга _boothdock._tcp, име „BoothDock" плюс името на компютъра). Приложенията, които го търсят, го намират автоматично.
Блокиране: Ако дадено устройство изпрати грешна парола десет пъти за десет минути, то се блокира за 15 минути. Самият този компютър никога не се блокира.
Само в собствената мрежа: Паролата минава през мрежата некриптирана. Използвай мрежовия режим само в собствената си защитена Wi-Fi мрежа – не в отворената Wi-Fi мрежа за гости на мястото на събитието.
Защитна стена: Инсталацията създава правилото, само за частни мрежи. Ако редът за състояние показва предупреждение за защитната стена, инсталирай отново BoothDock Studio или го разреши в Windows чрез „Разрешаване на приложение през защитната стена". Ако Windows третира Wi-Fi мрежата като публична, устройствата не могат да влязат – задай профила Частна в свойствата на мрежата.

Команди

Команда	Действие
`start?mode=print`	Стартира сесия. Режими: `print` (снимка), `gif`, `boomerang`, `slowmo` (360°; без 360° – Бумеранг), `video`, `ai`. Работи само от началния екран, само с разрешен режим и не при заключен бокс.
`cancel`	Прекъсва текущата сесия и се връща към началния екран.
`status`	Връща в `Data`: режим за гости вкл./изкл., текущ екран, режим, заключен да/не.
`print?count=1`	Отпечатва последния резултат отново (от 1 до 10 листа). Видеата не могат да се печатат.
`lockscreen/show`	Заключва бокса със съобщението „Един момент – веднага продължаваме." Административният ъгъл остава достъпен.
`lockscreen/exit`	Отменя заключването.
`share/email?email=…`	Изпраща последния резултат по имейл – изисква сдвояване с Hub и действието с резултата „Получите чрез имейл“ (Система → Работа → Действия с резултата (гост); до версия 1.4.0 превключвателят „Снимка по имейл (гост)“ под Дизайн → Екрани).
`share/sms`	Не съществува; отговорът го казва честно (`IsSuccessful: false`).
`createtestevent?name=…`	Създава тестово събитие и го прави активно. `Data` съдържа `eventId` и `eventName`. Без име се създава такова с дата.
`deletetestevent?eventId=…`	Изтрива тестово събитие, създадено през API – никога други събития.
`ping`	Проверява без парола дали API работи.

Ако боксът не отговори до 15 секунди, връща се IsSuccessful: false с пояснение.

Експорт в реално време

В същия раздел в полето Папка за експорт избираш цел – например USB флашка или облачна папка (OneDrive, Dropbox). Всеки готов файл попада там веднага, подреден по събитие и тип (разпечатки, оригинали, GIF файлове, видеа – всеки тип може да се изключи поотделно). Ако флашката липсва за кратко, боксът допълва файловете по-късно. Ако гост изтрие сесията си на автомата, изчезват и копията.

Старт с дистанционно

В същия раздел под Старт с дистанционно запомняш клавиш. Презентерите, USB бутоните и крачните превключватели обикновено изпращат интервал; той е зададен по подразбиране. При Стартира избираш какво задейства клавишът на началния екран: Като докосване (нормален процес) или направо режим, например 360° на платформата. В BoothDock Studio 1.4.0 и по-старите версии клавишът е наличен само за 360°, виж 360° / Забавен каданс.

Отстраняване на проблеми

Нищо не се случва: Има ли нещо в протокола? Уебхуковете пишат в webhooks.log (до версия 1.4.0: ausloeser.log), API – в lokale-api.log, и двата в папката %LocalAppData%\Boothdock Studio\logs. Отхвърлените заявки (грешна парола, чуждо устройство) се записват там най-много веднъж на минута.
„Invalid password." – копирай паролата отново; след Нова парола старата вече не важи.
„The booth is not on the start screen …" – start работи само от началния екран. Първо cancel, после start.
„Too many failed attempts …" – устройството е изпратило грешна парола твърде много пъти. Изчакай 15 минути и провери паролата.
Телефонът не достига бокса, а на компютъра всичко работи: почти винаги причината е защитната стена на Windows или Wi-Fi мрежа, водена като публична – виж по-горе. Редът за състояние съобщава и за двата случая.