Інструкції користувача

Мережеві доступи

Незалежно від сценарію, за яким використовується ПЗ Соловейко.Медіа, для коректної роботи, клієнт повинен забезпечити підключення до інтернету та відсутність обмежень у доступі до сервісів описаних далі.

Сценарій №1

Додаток "soloveyko" для відтворення медіаконтенту потребує доступи в інтернеті до наступних сервісів:

Сервіс
Домен (DST)
Порт / Протокол
Призначення
Backend
api.soloveyko.media є CNAME для
d-mqzuxjv2g8.execute-api.eu-central-1.amazonaws.com
443/https/tcp
Конфігурація
File Storage
  • soloveyko.s3.eu-central-1.amazonaws.com
  • cdn.soloveyko.media
Завантаження медіаконтенту
SQS
sqs.eu-central-1.amazonaws.com
Обмін службовими командами
Package Repository
nest.soloveyko.media
Завантаження пакету з додатком, контроль версії додатку
NTP
Використовуються ті, що налаштовані на операційний системі обладнання клієнта;
Синхронізація часу
DNS
Ідентифікація доменних імен

Сценарій №2

Комплект Soloveyko.Box із встановленим повним набором ПЗ потребує мережеві доступи з сценарія 1, а також наступні мережеві доступи:

Сервіс
Домен (DST)
Порт / протокол
Призначення
NTP
*.ua.pool.ntp.org
123/udp
Синхронізація часу
DNS
IP-адреса, отримана від DHCP, а також:
1.1.1.1
8.8.8.8
8.8.4.4
53/udp
Ідентифікація доменних імен
OpenVPN
gloryhollow.soloveyko.media
80/tcp
443/tcp
8443/tcp
Віддалений доступ для служби підтримки

У випадку використовування клієнтом комплекту Soloveyko.Box — ініціатором всіх нових з'єднань виступають додатки (soloveyko та ін.), встановлені на Soloveyko.Box.

У випадку звернень до служби підтримки, вона може відкривати Soloveyko.Box віддалений доступ (SSH) або відправляти запити (HTTPS) на Soloveyko.Box всередині ініційованого ним OpenVPN шифрованого з'єднання.

Визначення IP-адрес доменів

За необхідності ІР-адреси для вказаних доменних імен можуть бути визначені клієнтом власноруч за допомогою, наприклад, утиліти nslookup. У випадку обмежень доступів за "білим" списком ІР-адрес, клієнт повинен забезпечити оновлення "білого" списку.

SRC і DST адреси запитів

Адреса джерела (SRC) вихідних запитів на вказані сервіси буде обрана в залежності від налаштувань мережі клієнта.
Пристрій із встановленим додатком "soloveyko", який виступає джерелом з'єднання, ініціює їх використовуючи налаштування, отримані за допомогою протоколу DHCP (Dynamic Host Configuration Protocol) або налаштовані клієнтом власноруч.

Гарантії

Ми гарантуємо, що домен soloveyko.media та всі сабдомени, а також відповідні сервери та/або сервіси належать компанії Соловейко.Медіа та адмініструються співробітниками компанії.

Встановлення додатку Soloveyko

Увага!
Наведена інструкція розрахована на людину, яка має досвід використання операційних систем GNU/Linux, а також досвід роботи з терміналом.
Уважно прочитайте всю інструкцію до кінця, перед тим як виконувати будь-які наведені команди.
Всі наведені команди, системні шляхи, назви змінних, значення змінних тощо чутливі до регістру.

Вимоги до середовища операційної системи

Додаток "soloveyko" працює на операційних системах GNU/Linux. На даний момент підтримуються Debian-based дистрибутиви під керуванням системного менеджера systemd. Коректна робота можлива на дистрибутивах не старіше, ніж Debian 12 або Ubuntu 22.04. Підтримуються наступні архітектури процесорів: amd64/x86_64, ARMv7/armhf, ARMv8/arm64.
Додаток розповсюджується у виді deb-пакунку, для встановлення якого необхідний відповідний менеджер пакунків. Завантаження і встановлення відбувається з офіційного репозиторію Соловейко.Медіа. Наведені нижче інструкції призначені для менеджеру пакунків apt. Також необхідна наявність в системі наступних утиліт і пакунків: curl, gpg, ca-certificates.

Процес встановлення

Додавання офіційного репозиторію Соловейко.Медіа

Перевіряємо і створюємо директорії для ключа підпису та файлу посилання на репозиторій, якщо такі відсутні:
if [ ! -d /etc/apt/keyrings/ ]; then mkdir -p /etc/apt/keyrings/; fi
if [ ! -d /etc/apt/sources.list.d/ ]; then mkdir -p /etc/apt/sources.list.d/; fi
Завантажуємо публічний ключ підпису пакунку:
curl -fsSL https://nest.soloveyko.media/linux/deb/gpg | gpg --dearmor -o /etc/apt/keyrings/Soloveyko.Media.gpg
Завантажуємо файл посилання на репозиторій:
curl -fsSL https://nest.soloveyko.media/linux/deb/Soloveyko.Media.Production.sources -o /etc/apt/sources.list.d/Soloveyko.Media.Production.sources
Виконуємо оновлення індексів репозиторіїв:
apt update
Після успішного виконання наведених команд, у пошуку буде доступний пакунок "soloveyko", а також додаткові пакунки:
apt search soloveyko
1.png

Попередні налаштування та встановлення пакунку

Під час встановлення буде створено користувача soloveyko від імені якого буде працювати додаток, а також створено ряд директорій і файлів:

Користувач soloveyko призначається власником директорій, у яких створюються файли під час роботи, а також він додається до груп:
audio, video, users, render, pulse, pulse-access.

Додаток soloveyko , під час комунікації з сервісами Соловейко.Медіа, використовує спеціальний ідентифікатор. Цей ідентифікатор повинен бути унікальним і формується в процесі встановлення з MAC-адреси мережевого інтерфейсу, який має одне з наступних імен: eth0, enp*, end0, eno* , а також, за необхідності, може бути переданий перед початком встановлення за допомогою оголошення системної змінної SOLOVEYKO_HWID перед початком встановлення. Власноруч переданий ідентифікатор повинен відповідати наступним вимогам:

Додаток soloveyko має можливість відтворювати декілька звукових файлів одночасно, відповідно створюючи декілька потоків, що вимагає наявного і працюючого у системі звукового сервера. За замовчуванням використовується pulseaudio , для якого є можливість встановити режим роботи на системному рівні шляхом створення відповідного сервісу. Цей режим зручно використовувати на серверних варіантах операційних систем, які працюють середовища робочого столу та без здійснення входу користувачами. Увімкнненя створення сервісу здійснюється оголошенням системної змінної SOLOVEYKO_SETUP_SYSTEMWIDE_PULSEAUDIO перед початком встановлення.
Якщо в операційній системі встановлено пакунки для роботи графічного середовища (xorg або wayland), додаток встановиться із підтримкою відтворення відео і буде примусово розгортатись на весь екран. Якщо така поведінка небажана, можна увімкнути прихований режим роботи, у якому відтворюватиметься лише звук. Увімкнненя прихованого режиму роботи здійснюється оголошенням системної змінної SOLOVEYKO_AUDIO_ONLY_HEADLESS_MODE перед початком встановлення.
На деяких операційних системах було помічено зупинку роботи звукової та/або відео підсистем, якщо користувач не здійснив вхід у систему. Для вирішення цієї проблеми, під час встановлення пакунку, може бути створено відповідний файл модифікації сервісу getty за шляхом /etc/systemd/system/getty@tty1.service.d/autologin.conf для здійсненя автоматичного входу користувача soloveyko . Слід зауважити, що це накладає безпекові ризики і повинно використовувати із повним усвідомленням власних дій. Увімкнненя здійснюється оголошенням системної змінної SOLOVEYKO_AUTOLOGIN_USER перед початком встановлення.

Перед початком встановлення пакунку, за необхідності, можуть бути оголошені системні змінні, для передачі налаштувань, відмінних від за замовчуванням:
Назва змінної Значення за замовчуванням Допустимі значення Призначення
SOLOVEYKO_HWID Відсутнє. Визначається в процесі встановлення.
Максимальна довжина 40 символів. Дозволені символи:
a-z - літери латинського алфавіту у нижньому регістрі;
A-Z - літери латинського алфавіту у верхньому регістрі;
0-9 - цифри;
- _ - мінус, нижнє підкреслення
 Ідентифікатор
SOLOVEYKO_NETWORK_DEVICE_NAME Відсутнє. Визначається в процесі встановлення. Відповідно до списку мережевих інтерфейсів Назва мережевого інтерфесу, MAC-адресу якого використовувати при створенні ідентифікатору
SOLOVEYKO_USER_NAME soloveyko Відповідно до правил іменування груп і користувачів Ім'я користувача, від якого працюватиме додаток
SOLOVEYKO_USER_GROUP soloveyko Відповідно до правил іменування груп і користувачів Група користувача
SOLOVEYKO_UID_GID 1488 Відповідно до правил іменування груп і користувачів ID-номер користувача і групи
SOLOVEYKO_AUDIO_ONLY_HEADLESS_MODE False True, False Прихований режим: відключити будь-який вивід зображення, відтворювати лише звук. 
SOLOVEYKO_AUTOLOGIN_USER False True, False Створити файл для автоматичного користувача в систему
SOLOVEYKO_USER_ADDITIONAL_GROUPS audio,video,users,render,pulse,pulse-access Відповідно до списку системних груп. Список вказується без пробілів, розділення комою. Додати користувача до наступних груп, окрім власної
SOLOVEYKO_LOG_PATH /var/log/soloveyko/ Відповідно до правил створення шляхів Директорія для логів
SOLOVEYKO_STORAGE_BASE /var/lib/soloveyko/ Відповідно до правил створення шляхів Директорія для даних
SOLOVEYKO_SETUP_SYSTEMWIDE_PULSEAUDIO False True, False Встановити файл сервісу для запуску звукового серверу на системному рівні
SOLOVEYKO_NO_ENABLE False True, False Не додавати сервіс soloveyko до автозапуску
SOLOVEYKO_NO_START False True, False Не запускати сервіс soloveyko після завершення встановлення
Всі наведені змінні повинні бути оголошеними перед початком встановлення пакунку і оголошуватись як змінні середовища за допомогою команди export . Значення наведених змінних, після встановлення, будуть збережені у файл /etc/soloveyko.env для застосування у подальших ітераціях встановлення або оновлення пакунку.
Встановлення додатку:
export SOLOVEYKO_SETUP_SYSTEMWIDE_PULSEAUDIO=True
# За необхідності прихованого режиму роботи:
# export SOLOVEYKO_AUDIO_ONLY_HEADLESS_MODE=True
apt install soloveyko helper-utils-soloveyko

Дії після встановлення

По успішному завершенню встановлення пакунку, у консоль буде виведено призначений ідентифікатор, який використовуватиме додаток, а також встановлені шляхи розміщення логів і даних.
2.png
Ідентифікатор необхідно власноруч вказати під час додавання пристрою у інтерфейсі платформи app.soloveyko.media.

Перевірка роботи додатку може бути здійснена за допомогою команди:
systemctl status soloveyko
3.png
Також можна переглянути логи:
mcview /var/log/soloveyko/soloveyko.log
Додаток має файл налаштувань /opt/soloveyko/config/override.yml, у якому можна внести деякі додаткові налаштування для роботи конкретного екземпляру додатку. Всі налаштування будуть збережені між перевстановленнями додоатку, окрім випадків повного видалення (apt purge soloveyko).
4.png
Вміст файлу відповідає синтаксису YAML. Далі наведено опис деяких корисних налаштувань:
Опція
Значення за замовчуванням
Допустимі значення
Призначення
raw
false
true, false
Завантажувати файли медіаплану без нормалізації гучності
enable_local_api
true
true, false
Включити API
host
0.0.0.0
Адреса мережевого інтерфейсу API
port
14880
1 - 65000
Порт API
history
20
1 - 100
Кількість файлів логів, які будуть збережені на диску
size
3
1 - 10
Розмір файлу логу в мегабайтах, при досягненні якого буде виконана ротація
ao
pulse
pipewire, pulse, alsa, jack, sdl, pcm
Назва звукового серверу

Допоміжні засоби

REST API

Додаток має модуль REST API для можливості здійснювати контроль роботи додатку всередині локальної мережі (потребує окремого налаштування фаєрволу). Далі наведено опис методів API:
Метод
Тип
Аргументи
Значення
Призначення
Приклад запиту
/reschedule
POST
Відсутні
Почати позачергове оновлення розкладів відтвоерння контенту
curl -X POST "http://127.0.0.1:14880/reschedule"
/refresh_device_config
POST
Відсутні
Синхронізувтаи конфігурацію додатку з платформою app.soloveyko.media
curl -X GET "http://127.0.0.1:14880/refresh_device_config"
/set_volume
POST
volume
volume_ad_and_promo
volume_system_sound
volume_when_system_sound
volume_while_air_alert
0 - 200
Встановити гучності незважаючи на всі налаштування отримані з платформи. Налаштування будуть актуальні до моменту наступного оновлення конфігурації або зміни гучності на сторінці керування на платформі app.soloveyko.media. Передавати необхідно всі аргументи
curl -X POST "http://127.0.0.1:14880/set_volume?volume=80&volume_ad_and_promo=80&volume_system_sound=80&volume_when_system_sound=80&volume_while_air_alert=80"
/play_filename
GET
filename
назва файлу з розширенням
Відтворити системне звукове сповіщення
curl -X GET "http://127.0.0.1:14880/play_filename?filename=default_location_closing.mp3"

Пакунок helper-utils-soloveyko та інші

Додатково до основного пакунку з додатком "soloveyko", в репозиторії знаходяться пакунки, які надають допоміжні функції, наприклад
Рекомендованим до встановлення є пакунок helper-utils-soloveyko, який містить утиліти для оновлення і моніторингу.

Інструкція користувача платформою Соловейко.Медіа

Вступ

Сайт app.soloveyko.media є частиною платформи Соловейко.Медіа, яка надає рішення для створення унікальної аудіовізуальної атмосфери в бізнесі. Платформа дозволяє керувати відтворенням аудіо та відео реклами, цифрового меню та унікальних сповіщень, сприяючи збільшенню середнього чека та додатковому заробітку на рекламі.

Через особистий кабінет користувачі можуть завантажувати зображення, відео, музику, створювати цифрове меню та керувати контентом на екранах зі своїх комп'ютерів, телефонів чи планшетів. Медіа-контент автоматично відтворюється на екранах у точках продажу відповідно до розкладу.

1. Локації та пристрої

Даний розділ дозваоляє керувати та моніторти усі підключені пристрої та локації.

image.pngМає основні поля для взаємодії:

  1. Локації - вкладка котра містить усі локації та пристрої вашої організації
  2. Вільні соловейчики - тут зщнаходяться соловейчики котрі не прив'язані до жодної локації
  3. Офлайн соловейчики - список пристроїв котрі наразі офлайн
  4. Пошук - пошук по локація/пристром/місту
  5. Загальна кількість онлайн/офлайн соловейчиків
  6. Меню локацій - випадаюче меню країна/область/місто
  7. Локація - дозволяє потрапити в меню відповаідної локації
1.1 Налаштування та взаємодія з локацією
   
  1. Відеозона - тут знаходяться відеопристрої
  2. Аудіозона - тут знаходяться відеопристрої
  3. Переглянути медіаплан - актуальний розклад локаціїї
  4. Прив'язати пристрій - додати пристрій у зону
  5. Пристрої - пристрої підключені до відповідної зони

  1. Тестовий виклик касира - якщо функція підключена, можна запустити тестовий файл котрий прозвучить на локації
  2. Тестовий виклик замовлення Глово - якщо функція підключена, можна запустити тестовий файл котрий прозвучить на локації
  3. Хвилина мовчання - кнопка включення/виключення хвилини мовчання. Якщо включено о 9:00 кожного днгя буде відтворюватись хвилина мовчання.
  4. Тестовий запукск хвилини мовчання - тестовий запуск хвилини мовчання на локації

  1. Ідентифікування локації - Редагування загальної інформаціїї локації
  2. Географія локації - геолокація (не використовується)
  3. Контактні особи - працівники локації (Управляючий/завтупник/керуючий)
  4. Години роботи локації - час відкриття та закриття локації. Пристрої орієнтуютсь на цей параметр, щоб розуміти коли починати та закінчувати відтворення контенту.
  5. Повітряна тривога - підключення сповіщення про повітряну тривогу, важливо встановити правильну область, тому що пристрої за цією інформацією відтворюють сповіщення про повітряним тривогам в україні
1.2 Завантаження звіту про всі підключенні пристрої

image.png

  1. У меню "Локації та пристрої", натисніть 3 краки
  2. У вікошку натисніть "Підключені пристрої"
  3. Після цього буде завантажений звіт по всім підключеним до локацій пристроями


2. Завантаження контенту на платформу

2.1 Створення плейлисту

        image.png

        image.png

2.2 Завантаження контенту

         image.pngimage.png

3. Створення та налаштування етерів

3.1. Створення етеру

ВАЖЛИВО! Так як це меню містить розклади для всіх видів пристроїв, рекомендуємо в назві етеру зазначати для яких пристроїв, або під які локації створено цей етер. Щоб у майбутньому не було проблем з навігацією серед купи етерів.

        image.png

        image.png


3.2. Створення розкладу

        image.png

        image.png

        image.png

3.3. Завантаження та налаштування контенту в етер:
   3.3.1 Завантаження звичайного контенту

До одного плейлиста можна додавати декілька діапазонів одночасно. В такому випадку плейлист буде транслюватись лише в обраних діапазонах дат.

  3.3.2 Завантаження промо контенту

До одного плейлиста можна додавати декілька діапазонів одночасно. В такому випадку плейлист буде транслюватись лише в обраних діапазонах дат.

3.3.3 Налаштування промо контенту

Для налаштування потрібно заповнити 4 поля у вкладці "Налаштування промо"

image.png

1) "Кожні # треків" - як часто промо блок буде потрапляти в ефір.

Наприклад: Якщо встановити значення 3, тоді проблок буде транслуватись кожні 3 треки зі звичайного плейлиста.
Якщо значення 4 то кожні 4 треки і т.д.

2) "Вид вставки" - як вставити промо блок відносно звичайного контенту

Наприклад: Якщо Поставити значення "ДО", тоді промо блок буде відтворюватись перед звичайним контентом, а якщо "ПІСЛЯ" то відтворення відбудеться після звичайного контенту. По суті це налаштування визначає послідовність звичайного та промо контенту.

3) "Кількість треків" - Яку кількість треків буде містити промо блок

Наприклад: Якщо значення буде стояти 4, тоді промо блок буде включати в себе 4 треки. Після відтворення 4-х промо роликів почнеться трансляція звичайного контенту. 

Значення може бути більше кількості треків у плейлисті, але потрібно мати на увазі, що в такому випадку треки будуть повторюватись у промо блоці по декілька разів.

4) "Вага" - кількість треків котрі будуть потрапляти до промо блоку з даного плейлиста

Наприклад: Якщо ми створили 2 плейлисти и виставили кожному з них різні значення "ваги", наприклад 1 і 2, тоді у кожен промо блок буде потрапляти 1 трек із плейлисту з вагою 1 та 2 треки із плейлисту з вагою 2.

На скріншоті нижче приведено приклад налаштувань промо контенту.
1) Кожні 3 треки буде запускатись промо блок
2) Промо блок буде відтворюватись до блоку із 3-х треків
3) Промо блок буде містити в собі 3 промо треки
4) Промоблок буде брати 2 треки з плейлисту Тест 2, та 1 трек з плейлисту Тест.

image.png

Виходячи з налашитувань вище медіаплан розкладу биде виглядати наступним чином, приклад на початку роботи розкладу:
Жовтим позначено промо блок - він іде до відтворення перших музикальних треків, та містить 1 трек з плейлисту ТЕСТ (Test audio), та 2 треки з плейлисту ТЕСТ 2 (Test audio 2, Test audio 2.1).
Рожевим позначено блок звичайного контенту - він містить 3 музикальні треки згідно до налаштувань "Кожні # треків".

image.png

Вкладка "Перегляд черги" відображає актуальну чергу відтворення медіаплану. Та має дві дотакові функції.
1) "Оновити чергу" - кнопка перезбиранне чергу відтворення роликів. Ця кнопка потрібна пізля внесення змін у розклад, щоб нові треки додались у чергу відтворення. 
2) "Синхронізувати чергу пристроїв" - кнопка відправляє на всі пристрої котрі прив'язані до цього ефіру оновлення розкладу.
ВАЖЛИВО! Кнопка не миттєво завантажує розклад на пристрої. Оновлення відбуваеться протягом 1 години після відправлення команди.

4. Рекламні кампанії

  4.1. Створення рекламної кампанії

Для аудіо та відео процес створення та налаштування рекламної кампанії нічим не відрізняються,, тому подальша інструкця буде зроблена на прикладі аудіо.

        - Оберіть зони на котрих ви плануєте запускати рекламну кампанію

         image.png

         - Оберіть локації на котрий має транслюватись рекламна кампранія

         - Натисніть "Підтвердити" у нижному правому куті вікна.

         - Натисніть "Додати локацію за ID"

         image.png

Зверніть увагу, на платформі Соловейко.Медіа кожна локація має власний індентифікатор.image.png

        - У вікні пропишіть ID локації,оберіть бажану для трансляції зону

image.png

         - Оберіть локації на котрий має транслюватись рекламна кампранія

         - Натисніть "Підтвердити" у нижному правому куті вікна

  4.2 Виведення рекламної кампанії в ефір

Початкове затвердження рекламної кампанії. На даному етапі кампанію ще можна редагувати перед виходом в ефір. 
Проміжне затвердження необхідно для перевірки налаштувань, або якщо є відповідальний за рекламу керівник, щоб він фінально погоджував налаштування виходу кампанії.

Під час проміжного затвердження кампанія змінює статус із "Чорновик" на "Очікує затвердження"
image.png

Після погодження рекламної кампанії, вона з'явиться у ефірі, та почне трансляцію на пристроях.
Статуст кампанії у загальному меню Реклами зміниться зі статусу "Очікує підтвердження" на ствтус "В етері"image.png

Після фінального погодження рекламної кампанії зміни можна вносити лише знявши кампанію з ефіру, або після її завершення.

4.3 Зняття рекламної кампанії з ефіру

Якщо необхідно повернути рекламну кампанію в етер зі змінами.

- Перейдить в скасовану рекламну компанію.
-Натисніть "Відновити"
- Вносьте зміни та затверджуйте ракламну кампанію згідно пунктам 3.1 та 3.2

4.4 Продовження рекламної кампанії

5. Ефірна довідка

5.1 Що таке Ефірна довідка

Це меню дозволяє користувачам завантажувати звіт по рекламі за необхідний період часу. Ви отримуєте Exel табличку зі списком рекламних роликів та  кількістю їх виходів.

5.2 Як працює Ефірна довідка

6. Налаштування організації

6.1. Користувачі та ролі

Як додати нового користувача

Інструкція для встановлення пристрою "Соловейко.Аудіо"

1. Підготовка до встановлення

2. Підключення пристрою

3. Перевірка підключення

4. Контакт із представником "Соловейко.Медіа"

Інструкція для встановлення пристрою "Соловейко.Відео"

1. Підготовка до встановлення

2. Підключення пристрою

3. Перевірка підключення

4. Контакт із представником "Соловейко.Медіа"

Вимоги для встановлення та налаштування

Фізичне підключення пристрою Соловейко:

Необхідні кабелі:

- Мережевий кабель (Ethernet);
- Аудіокабель (3,5 мм або RCA);
- Кабель живлення з блоком живлення (У комплекті з Соловейчиком).

Процес підключення:

- Мережевий кабель. 
Підключіть пристрій до мережевого комутатора або роутера.
- Аудіокабель.
З'єднайте аудіовихід пристрою із підсилювачем звуку за допомогою аудіокабелю.
- Живлення. 
Підключіть пристрій до електромережі через блок живлення. Блок живлення потрібно вставити в розетку на серверній стійці (обладнану безперебійником). 

Видача доступів:

Для коректної роботи пристроїв Соловейко, для них необхідно надати  доступи  до серверів Соловейко.Медіа.
94.158.94.148
195.189.226.201
185.25.118.68
185.69.154.217
49.13.26.111

протокол ICMP

протокол TCP на порти 80, 53, 443, 123, 8443
протокол UDP на порти 80, 53, 443, 123, 8443