Руководство пользователя приложения Twitch Widgets

Twitch Widgets — это консольное приложение предоставляющее дополнительные чат команды и виджеты для стримеров платформы Twitch.

Содержание

• Особенности
• Установка и запуск
• Как работает приложение
• Команды
  • !vote
  • !draw
• Настройки
  • twitch
  • commands
  • ngrok
• Интеграция с OBS
• Изменение дизайна виджетов через OBS
  • Текст
  • Фон
  • Фон элементов
  • Иконки
• Проблемы и решения
• Контакты

Особенности

• Создание событий: голосование и розыгрыш с помощью чат команд
• Виджеты для просмотра прогресса событий и интеграции с OBS
• Гибкий файл конфигурации
• Переносимое приложение (Portable)
• Не требует установки стороннего ПО

Установка и запуск

1. Добавьте бота на ваш Twitch канал с помощью ссылки подключения
2. Скопируйте сгенерированный пароль авторизации (Twitch Chat OAuth Password)
3. Скачайте последнюю версию приложения, и откройте любым текстовым редактором файл конфигурации config.json
4. Вставьте ранее скопированный пароль авторизации напротив ключа password и напишите название своего канала напротив ключа login. Значения обязательно должны быть заключены в двойные кавычки!
5. Запустите приложение twitch-widgets.
6. Для просмотра данных перейдите на веб-сайт http://localhost:80.

✔️ Пример правильно отредактированного файла конфигурации

"twitch": {
    "password": "oauth:1kxfnxefds3t8zupbm67fhsxd9z1fj",
    "login": "razie1l",
    "httpPort": 80,
    "ircPort": 433
}

✔️ Cобщение в консоли при успешном запуске

[16:19] Local web server URL: http://localhost:80
[16:19] Public web server URL: disabled
[16:19] Connected to razie1l Twitch channel

Примечание

• Сайт доступен на локальной машине и не "виден" из интернета.
• Для доступа к веб-сайту из интернета отредактируйте файл настроек sshForward или ngrok.

Как работает приложение

1. При запуске приложения происходит авторизация с Twitch API и предоставляется доступ к чату вашего Twitch канала.
2. На вашем компьютере создается локальный веб-сервер, который по средствам REST API предоставляет данные Twitch обработанные приложением.
3. Данные отображаются в виде виджетов на веб-сайте доступным по адресу http://localhost:80. Виджеты позволяют следить за пользовательскими событиями вашего канала в реальном времени.

Команды

Приложение предоставляет набор чат команд Twitch для создания событий. Каждая команда имеет приставку — специальный единый символ, который помогает идентифицировать команды и отделить их от простого текста в чате Twitch. По умолчанию приложение использует символ ! в качестве приставки.

!vote

Команда позволяет стримеру создавать голосования для пользователей между двумя участниками. Голосование неограниченно по времени.

Использование

После команды !vote перечислите участников голосования через пробел, например !vote Fnatic NaVi (имена участников не должны содержать пробелы и спец. символы).

После выполнения команды голосование считается открытым, виджет голосования будет доступен по адресу http://localhost:80/vote. Пользователи вашего канала теперь могут отдать свой голос за участника с помощью команды соответствующей его имени. Например !NaVi.

Для завершения голосования стримеру нужно написать команду !vote. Список голосов пользователей доступен по адресу http://localhost/vote/list

!draw

Команда позволяет стримеру создавать розыгрыши для пользователей за отведенное время.

Использование

После команды !draw через пробел укажите время в минутах, которое должен длится розыгрыш. Далее через пробел укажите текст, который будет отображаться в виджете на сайте. Обязательно заключите текст в двойные кавычки!

Пример: !draw 5 "УЧАСТВУЙТЕ В РОЗЫГРЫШЕ КРЕДИТОВ!"

Для запуска розыгрыша напишите команду !drawstart. Пользователи вашего канала теперь могут принять участие в розыгрыше с помощью команды !draw. По истечению времени на виджете отобразиться победитель, который будет выбран случайным образом.

Настройки

Настройки приложения задаются в файл конфигурации config.json, который находится в корневой директории приложения. Файл имеет расширение json.

JSON — это простой формат обмена данными состоящий из коллекции пар ключ/значение.
Объект — неупорядоченный набор пар ключ/значение. Объект начинается с { открывающей фигурной скобки и заканчивается } закрывающей фигурной скобкой. Каждое имя ключа сопровождается : двоеточием, пары ключ/значение разделяются , запятой.

Пример объекта #1

"pewdiepie"
{
    "followers": 10000000
}

Пример объекта #2

Объект вложен в другой объект

"vloggers": {
    "pewdiepie": {
        "followers": 10000000
    }
}

Файл содержит следующие объекты отвечающие за пользовательские настройки: twitch, commands, ngrok, sshForward. После редактирования настроек требуется перезапуск приложения.

twitch

Объект twitch хранит данные авторизации к Twitch API и настройки портов локального веб-сайта.

Ключ	Значение	Примечание
password	Пароль авторизации (Twitch OAuth)	Ссылка генерации пароля Значение обязательно должно быть заключено в двойные кавычки!
login	Логин Twitch/название канала	Значение обязательно должно быть заключено в двойные кавычки!
httpPort	Порт для веб-севера	При изменении порта веб-сайт будет доступен по следующему адресу http://localhost:ПОРТ Решение проблемы недоступности веб-сайта
ircPort	Порт для обмена данными с Twitch	Порт должен быть открыт в фаерволе/брандмауэре и виден из вне

Объект twitch

"twitch": {
    "password": "oauth:j8sw4m4ao19551vdpidp5e0c3zxguc",
    "login": "razie1l",
    "httpPort": 80,
    "ircPort": 433
}

commands

Объект commands хранит коллекцию объектов отвечающих за настройку определенной чат команды. Имена ключей вложенных объектов редактировать не разрешается!

Ключ	Значение	Примечание
prefix	Символ приставки команд	Подробная информация в разделе Команды Значение обязательно должно быть заключено в двойные кавычки!
notify	При значении true включает сообщения приложения в чате Twitch, false отключает сообщения
name	Название команды для её вызова	Значение обязательно должно быть заключено в двойные кавычки!
accessFlag	Значение 0 - позволит любому пользователю использовать команду, 1 - только стримеру, 2 - модератору, 3- стримеру и модератору

Объект commands

"commands": {
    "prefix": "!",
    "notify": true,
    "vote": {
        "name": "vote",
        "accessFlag": 3
    },
    "draw": {
        "name": "draw",
        "accessFlag": 3
    },
    "drawstop": {
        "name": "drawstop",
        "accessFlag": 3
    },
    "drawstart": {
        "name": "drawstart",
        "accessFlag": 3
    }
}

✔️ Правильный пример переименования команд

Команда !draw была переименована в $PRIZE

"commands": {
  "prefix": "$",
  "notify": true,
  "vote": {
      "name": "vote",
      "accessFlag": 3
  },
  "draw": {
      "name": "PRIZE",
      "accessFlag": 3
  },
  "drawstop": {
      "name": "drawstop",
      "accessFlag": 3
  },
  "drawstart": {
      "name": "drawstart",
      "accessFlag": 3
  }
}

❌ Неправильный пример переименования команды

Команда !draw не была переименована в $PRIZE. Структура файл конфигурации теперь повреждена!

"commands": {
  "prefix": "$",
  "notify": true,
  "vote": {
      "name": "vote",
      "admin": true
  },
  "PRIZE": {
      "name": "draw",
      "admin": false
  },
  "drawstop": {
      "name": "drawstop",
      "admin": true
  },
  "drawstart": {
      "name": "drawstart",
      "admin": true
  }
}

ngrok

Объект ngrok отвечает за доступ к веб-сайту из интернета.

Установка

1. Загрузите утилиту ngrok
2. Поместите утилиту в папку с приложением
3. Настройте файл конфигурации
4. Запустите приложение

Ключ	Значение	Примечание
enable	При значении true веб-сайт будет доступен из интернета, false отключает доступ из вне	При включении настройки адрес сайта будет указан в консоле приложения в сообщении Public web server URL: По умолчанию используется динамический URL адрес сайта. Адрес меняется после каждого запуска приложения, чтобы сделать адрес статическим (постоянным) требуется платная подписка хотя бы на BASIC план ngrok. Ключи перечисленные ниже в таблице необходимы для настройки статического адреса.
proto	Одно из значений: http, tcp, tls	Значение обязательно должно быть заключено в двойные кавычки!
auth	Строка в формате user:pwd	Http basic authentication for tunnel Значение обязательно должно быть заключено в двойные кавычки!
subdomain	Имя субдомена	Reserved tunnel name. Expamle: https://alex.ngrok.io Значение обязательно должно быть заключено в двойные кавычки!
authtoken	Token	Your authtoken from ngrok.com Значение обязательно должно быть заключено в двойные кавычки!
region	Одно из значений: us, eu, au, ap, sa, jp, in	ngrok regions Значение обязательно должно быть заключено в двойные кавычки!

Объект ngrok

"ngrok": {
    "enable": false,
    "proto": "http",
    "auth": "",
    "subdomain": "",
    "authtoken": "",
    "region": "us"
}

sshForward

Объект sshForward отвечает за доступ к веб-сайту из интернета (альтернативный способ). Данная опция требует версию Windows не менее 10 или установленный SSH-клиент.

Ключ	Значение	Примечание
enable	При значении true веб-сайт будет доступен из интернета, false отключает доступ из вне	При включении настройки адрес сайта будет указан в консоле приложения в сообщении Public web server URL: По умолчанию используется динамический URL адрес сайта. Адрес меняется после каждого запуска приложения.
reconnect	Время в миллисекундах через которое будет произведена попытка переподключения при потере соединения. 0=откл.

Интеграция с OBS

Отобразите прогресс ваших событий прямо на стриме.
Для этого выполните следующие шаги:

1. Перейдите на веб-сайт http://localhost:80 и откройте страницу с нужным виджетом
2. Скопируйте URL страницы из браузера
3. В OBS создайте новый источник Браузер и вставьте ранее скопированный URL в поле Адрес URL
4. Поставьте чекбокс ☑️ напротив Отключать, когда не видим и Обновить браузер, когда сцена становиться активной
5. Готово! Теперь можно запускать событие с помощью чат команд Twitch.

Примечание

• Чтобы просматривать виджеты в режиме браузера в источниках OBS нажмите на Браузер -> Взаимодействовать. Двойной клик мышкой по заднему фону виджета откроет главную страницу.
• Если OBS показывает не актуальную информацию в виджете выберете Браузер в источниках и нажмите Обновить.
• По умолчанию OBS применяет прозрачный фон к страницам. Чтобы сделать фон непрозрачным удалите свойство background-color или все свойства из поля CSS.

Изменение дизайна виджетов через OBS

Для изменения дизайна виджетов отредактируйте поле CSS выбрав Браузер в Источники OBS.

Текст

За цвет текста виджетов отвечает CSS свойства color. Для изменения цвета пропишите новое значение color в элементе body (черный по умолчанию) и в классе .color-a для второстепенного цвета (красный по умолчанию). В примере ниже основной текст теперь томатный, а второстепенный бирюзовый.

body {
    color: Tomato;
}
.color-a { 
    color: #008080; 
}

Фон

За фоновый цвет виджетов (подложку) отвечает CSS свойство background-color элемента body. По умолчанию используется белый цвет фона, в примере ниже розовый.

body {
    background-color: hotpink;
}

В этом примере прозрачный фон.

body {
    background-color: rgba(0, 0, 0, 0);
}

Фон элементов

Некоторые элементы используют класс .color-bg-a и .color-bg-b для применения цвета фона. Изменим цвет прогресса голосования на зеленый для первого участника и желтый для второго.

.color-bg-a {
    background-color: green;
}
.color-bg-b {
    background-color: yellow;
}

Иконки

За цвет иконок отвечает свойство fill класса icon.

.icon {
    fill: green;
}

Проблемы и решения

Приложение закрывается

После сбоя в папке приложения создается crash.log. Откройте файл любым текстовым редактором, и проверьте сообщения ошибок.

Описание ошибок:
listen EADDRINUSE: address already in use :::80 - см. Веб-сайт не доступен
Configuration file not found in ... - отсутствует файл конфигурации config.json

При наличии других ошибок создайте Issue и прикрепите файл crash.log

Чат команды не работают

Проверьте консоль приложения на наличие сообщений Failed to connect to Twitch channel или Login authentication failed. При наличии таких сообщения проверьте правильность введенных данных авторизации в файле config.json (поля password и login). Вам может потребоваться сгенерировать пароль авторизации снова (см. раздел Установка и запуск). В случае отсутствии сообщений возможно был поврежден файл конфигурации config.json, попробуйте скачать приложение еще раз.

Веб-сайт не доступен

Причиной может быть использование порта на котором запущен веб-сервер другой программой. В таком случае отредактируйте поле httpPort файла конфигурации config.json и укажите любой свободный порт, например 3000.

Контакты

По вопросам сотрудничества свяжитесь со мной через:
[email protected]
Steam
Discord сервер Alliance