← Всички статии

BoothDock · Wiki

Уебхукове и API

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

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

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

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

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

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

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

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

На iPad, iPhone и Mac има само адрес. Там http:// работи само в локалната мрежа (IP адрес или .local) – значи Shelly, WLED и Tasmota в Wi-Fi мрежата работят. Адресите в интернет изискват https://.

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

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

Отделен адрес за всяко събитие

От версия 1.5.10 в Отделен адрес за всяко събитие (по избор) можеш допълнително да дадеш на всяко събитие собствен адрес – например за контакт Shelly, WLED или Tasmota в Wi-Fi мрежата, които превключват при обратното броене или при снимането. Пример за countdown_start: http://192.168.1.50/relay/0?turn=on.

Боксът извиква този адрес в допълнение към програмата и адреса по-горе, като обикновен GET без добавени стойности. Досегашният адрес и съществуващите скриптове продължават да работят без промяна. countdown идва всяка секунда; при file_upload боксът извиква собствения адрес веднъж на сесия (общия адрес – все така за всеки файл).

Събития

СъбитиеКогаПараметри
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: албум (име на събитието)
lead_submittedГост е изпратил формуляра Данни за гости (формуляр) (от 1.5.0)– (самите отговори са само в CSV експорта)
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. Работи само от началния екран, само с разрешен режим и не при заключен бокс. С шаблон, стил и фон: виж по-долу.
auswahl?mode=printВръща в Data какво може да се избира в този режим: vorlagen (Id и име; празно, ако е разрешен само един шаблон – тогава той е в vorgabeVorlage), hintergruende за всеки шаблон и в режим ai – stile (от 1.5.13).
cancelПрекъсва текущата сесия и се връща към началния екран.
statusВръща в Data: режим за гости вкл./изкл., текущ екран, режим, заключен да/не – от 1.5.13 и sperrgrund (manuell или zeitfenster) и oeffnetUm.
print?count=1Отпечатва последния резултат отново (от 1 до 10 листа). Видеата не могат да се печатат.
lockscreen/showЗаключва бокса със съобщението „Един момент – веднага продължаваме." или с твой собствен текст и изображение (виж „Заключен екран“ по-долу). Административният ъгъл остава достъпен. От 1.5.13 заключването се запазва и след рестарт на приложението.
lockscreen/exitОтменя заключването – от 1.5.13 и заключването по времеви прозорец, до следващата смяна.
share/email?email=…Изпраща последния резултат по имейл – изисква сдвояване с Hub и действието с резултата „Получите чрез имейл“ (Система → Работа → Действия с резултата (гост); до версия 1.4.0 превключвателят „Снимка по имейл (гост)“ под Дизайн → Екрани).
share/smsНе съществува; отговорът го казва честно (IsSuccessful: false).
createtestevent?name=…Създава тестово събитие и го прави активно. Data съдържа eventId и eventName. Без име се създава такова с дата. Само извън режима за гости (от 1.5.4).
deletetestevent?eventId=…Изтрива тестово събитие, създадено през API – никога други събития. Само извън режима за гости (от 1.5.4).
pingПроверява без парола дали API работи.

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

Стартиране на сесия с шаблон, стил и фон

От версия 1.5.13 start приема избора директно – тогава боксът пропуска точно тези екрани за избор:

  • vorlage=<Id> (или template=) – шаблонът, само в режим print (снимка). Id-тата се получават с auswahl?mode=print.
  • stil=<Id> (или style=) – AI стилът, само в режим ai.
  • hintergrund=<Id> (или background=) – фонът при изрязването, съобразен с шаблона.

Пример: http://localhost:1500/api/start?mode=print&vorlage=hochzeit-gold&hintergrund=strand&password=ТВОЯТА-ПАРОЛА

Неизвестно или неподходящо Id не стартира сесия: IsSuccessful е false, а ErrorMessage посочва причината. Съгласието за поверителност и формуляра за данни на гостите боксът продължава да показва сам – те се отнасят за госта пред бокса и не могат да бъдат изпреварени през API.

Заключен екран

В Събития → Заключен екран (от 1.5.13) определяш какво показва заключеният бокс: собствен текст, собствено изображение и – при времеви прозорец – голямо обратно броене до отварянето.

  • Времеви прозорец за всяко събитие: С Отваря в и Затваря в боксът е заключен преди началото и след края.
  • Отключване на устройството: Ако е зададен ПИН на оператора (Система → Защита), заключеният екран показва малък катинар. Който знае ПИН-а, отключва бокса. Отключен преди началото, той остава отворен до края.
  • Дистанционно: В Hub под Кабини заключваш и отключваш всеки бокс, който поддържа това (Studio от 1.5.13). Същото става и чрез BoothDock Station и с lockscreen/show / lockscreen/exit.

Текуща сесия не се прекъсва нито от заключването от Hub, нито от времевия прозорец – боксът се заключва, щом гостът приключи.

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

В същия раздел: всеки готов файл попада веднага на самия бокс (Локално копие) – и без Hub, подреден по събитие и тип (разпечатки, оригинали, GIF файлове, видеа – всеки тип може да се изключи). Това копие никога не се изтрива автоматично. В USB флашка / втора папка добавяш втора цел: Автоматичен запис на USB флашка записва на всяка поставена флашка, Наваксване на пропуснати файлове дописва това, което е създадено без флашка. Или въвеждаш Фиксирана втора папка (с предимство), например облачна папка (OneDrive, Dropbox). Ако гост изтрие сесията си на автомата, изчезват и копията. На iPad и iPhone: В приложението Файлове под „На моя iPad › BoothDock Studio › Export“. В BoothDock Studio 1.5.3 и по-стари вместо това има само Папка за експорт.

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

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

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

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

Следващи стъпки