Поддерживаемые заголовки

При загрузке удалённой подписки Prizrak-Box считывает определённые HTTP-заголовки ответа от сервера. Эти заголовки позволяют провайдерам подписок управлять метаданными профиля, отображением трафика, автоматическим обновлением, логотипом, объявлениями и другим.

Заголовки нечувствительны к регистру. Неизвестные заголовки игнорируются без ошибок.

Встроенные заголовки

Если сервер не может устанавливать HTTP-заголовки ответа (например, статический хостинг), можно встроить заголовки в виде комментариев в начале содержимого подписки:

#profile-title: Моя VPN
#subscription-userinfo: upload=1073741824; download=5368709120; total=107374182400; expire=1893456000

Встроенные комментарии используют те же имена, что и HTTP-заголовки, с префиксом #. Они работают как запасной вариант — HTTP-заголовки ответа всегда имеют приоритет над встроенными.

Заметка

Заголовки с иконкой управляются самой панелью Remnawave автоматически. Добавлять их вручную через Правила ответов или настройки заголовков подписки не нужно — Remnawave отправляет их сам.

---

Метаданные профиля

Profile-Title

Отображаемое имя подписки в Prizrak-Box.

Свойство	Значение
Тип	string
Кодировка	UTF-8 или Base64 (префикс base64:)

Пример:

Profile-Title: Моя VPN подписка
Profile-Title: base64:TW9yIFZQTiDQv9C+0LTQv9C40YHQutCw

Если Profile-Title отсутствует, приложение использует имя файла из заголовка Content-Disposition, затем генерирует имя вида Sub-2024-01-01.

Profile-Logo

URL изображения для логотипа подписки в приложении.

Свойство	Значение
Тип	string (URL)
Поддерживаемые форматы	PNG, SVG
Максимальный размер	2 МБ
Разрешённые схемы	http, https

Пример:

Profile-Logo: https://example.com/logo.png

Логотип загружается при получении подписки и кешируется локально. Пустой или недействительный URL удаляет кешированный логотип.

Content-Disposition

Используется как запасной источник названия профиля, если Profile-Title отсутствует.

Свойство	Значение
Тип	string
Разбираемое поле	параметр filename

Пример:

Content-Disposition: attachment; filename="my-vpn.yaml"

Значение filename (без расширения) становится названием профиля, если Profile-Title не задан.

---

Информация о трафике

Subscription-Userinfo

Статистика использования трафика, отображаемая в карточке профиля.

Свойство	Значение
Тип	string (пары ключ=значение через точку с запятой)
Поля	upload, download, total, expire
Единицы	Байты (для трафика), Unix timestamp (для expire)

Пример:

Subscription-Userinfo: upload=1073741824; download=5368709120; total=107374182400; expire=1893456000

Поле	Описание
upload	Байт выгружено
download	Байт загружено
total	Общая квота трафика в байтах
expire	Время истечения как Unix timestamp

---

Настройки обновления

Profile-Update-Interval

Задаёт интервал автоматического обновления подписки.

Свойство	Значение
Тип	integer
Единица	Часы

Пример:

Profile-Update-Interval: 24

При наличии этого заголовка Prizrak-Box автоматически обновляет подписку с заданным интервалом в часах.

---

Ссылки

Profile-Web-Page-Url

URL главной страницы или портала провайдера подписки.

Свойство	Значение
Тип	string (URL)

Пример:

Profile-Web-Page-Url: https://myvpn.example.com

Отображается в деталях профиля как кликабельная ссылка.

Support-Url

URL службы поддержки или контактов (например, Telegram-канал, служба помощи).

Свойство	Значение
Тип	string (URL)

Пример:

Support-Url: https://t.me/myvpn_support

Отображается рядом с профилем для обращения в поддержку.

Subscription-Renew-Url

Прямая ссылка на страницу продления/оплаты подписки.

Свойство	Значение
Тип	string (URL)

Пример:

Subscription-Renew-Url: https://myvpn.example.com/renew?id=abc123

При наличии заголовка приложение показывает точку входа «Продлить подписку» в нескольких местах: в редакторе профиля, значком рядом с профилем в главном окне и в списке профилей, а также — когда сейчас пройден один из порогов Notify-Expire-Days/Notify-Traffic-Percent (см. ниже) — кнопкой на всю ширину карточки профиля. Без заголовка ничего из этого не показывается, профиль работает как обычно.

---

Напоминания о подписке

Эти заголовки настраивают клиентские напоминания о приближающемся или наступившем истечении подписки, а также о расходе трафика — показываются как нативные уведомления ОС, а пока порог пройден — ещё и кнопкой «Продлить подписку» под карточкой профиля (см. Subscription-Renew-Url выше).

Notify-Expire-Days

Пороги «за сколько дней до истечения подписки напомнить».

Свойство	Значение
Тип	string (список целых чисел через запятую)
Диапазон	1–365 (значения вне диапазона отбрасываются)

Пример:

Notify-Expire-Days: 1,3,7

Notify-Traffic-Percent

Пороги «на каком проценте использованного трафика напомнить».

Свойство	Значение
Тип	string (список целых чисел через запятую)
Диапазон	1–100

Пример:

Notify-Traffic-Percent: 80,90,100

Notification-Subs-Expire

Упрощённый вариант для панелей, которые не хотят указывать конкретные дни (некоторые панели в стиле Happ отправляют только этот заголовок).

Свойство	Значение
Тип	string (boolean)
Значения	true

Пример:

Notification-Subs-Expire: true

Если значение true, а Notify-Expire-Days при этом отсутствует, приложение включает напоминания об истечении с зашитыми по умолчанию порогами 1, 3 и 7 дней.

Эти заголовки требуют явного согласия

Уведомления об истечении и о трафике срабатывают только если панель отправила хотя бы один из заголовков Notify-Expire-Days, Notify-Traffic-Percent или Notification-Subs-Expire. Это верно, даже если Subscription-Userinfo уже содержит expire/total — приложение не придумывает пороги напоминаний самостоятельно. Если ни один из трёх заголовков не отправлен, уведомления-напоминания не показываются вне зависимости от локальной настройки «Напоминания о подписке» в приложении (эта настройка — разрешение на показ, а не источник самих порогов).

Кнопка продления ориентируется на самый дальний порог

Кнопка «Продлить подписку» (см. Subscription-Renew-Url) реагирует на наибольшее значение из Notify-Expire-Days. Например, при Notify-Expire-Days: 1,5,10 кнопка появится за 10 дней до истечения и останется видимой весь обратный отсчёт 10 → 5 → 1 → истекло, а не только в моменты ровно 1/5/10 дней. В отличие от push-уведомлений, кнопка работает и вовсе без заголовка Notify-Expire-Days — тогда она ориентируется на зашитые по умолчанию пороги 1/3/7 дней как любезность, — но по трафику процент никогда не придумывается: без явного Notify-Traffic-Percent кнопка вообще не учитывает расход трафика.

---

Объявления

Announce

Текстовое объявление, отображаемое в приложении как баннер на карточке профиля.

Свойство	Значение
Тип	string
Максимальная длина	200 символов
Кодировка	UTF-8 или Base64 (префикс base64:)

Примеры:

Announce: Техническое обслуживание в субботу 02:00–04:00 UTC
Announce: base64:0KLQtdGF0L3QuNGH0LXRgdC60L7QtSDQvtCx0YHQu9GD0LbQuNCy0LDQvdC40LU=

Announce-Url

URL, на который ссылается баннер объявления.

Свойство	Значение
Тип	string (URL)

Пример:

Announce-Url: https://status.myvpn.example.com

Нажатие на баннер объявления в приложении открывает этот URL.

---

Миграция URL и резервные адреса

Эти заголовки реализуют миграцию URL подписки — провайдеры могут перенести подписку на новый адрес без ручного обновления URL пользователями.

new-url

Указывает клиенту заменить весь URL подписки на новый.

Свойство	Значение
Тип	string (полный URL)
Приоритет	Наивысший — имеет приоритет над new-domain
Переходы	Максимум 3 последовательные миграции

Пример:

new-url: https://new.example.com/subscription/abc123

После получения этого заголовка Prizrak-Box немедленно сохраняет новый URL и выполняет повторную загрузку с него. Исходный URL навсегда заменяется в профиле.

new-domain

Указывает клиенту заменить только хост URL подписки, сохраняя путь и строку запроса.

Свойство	Значение
Тип	string (только хост, без схемы и пути)
Пример значения	new.example.com или new.example.com:8443

Пример:

new-domain: cdn.example.com

Если текущий URL подписки — https://old.example.com/sub/abc, результат будет https://cdn.example.com/sub/abc.

fallback-url

Альтернативный полный URL для использования, если основной URL подписки недоступен (не-2xx или ошибка соединения).

Свойство	Значение
Тип	string (полный URL)
Сохранение	Да — записывается в профиль для будущих запросов

Пример:

fallback-url: https://backup.example.com/subscription/abc123

Prizrak-Box сначала пробует основной URL. При неудаче переключается на fallback-url. Значение резервного адреса обновляется (или очищается) при каждом успешном запросе.

fallback-domain

Альтернативный домен для подстановки в основной URL при его недоступности.

Свойство	Значение
Тип	string (только хост)
Сохранение	Да — записывается в профиль

Пример:

fallback-domain: backup.example.com

Если основной URL — https://main.example.com/sub, этот резерв пробует https://backup.example.com/sub.

Порядок приоритетов резервирования

Порядок перебора: основной URL → fallback-url → основной URL с fallback-domain. Используется первый ответ со статусом 2xx.

---

Управление интерфейсом Android Только Android

Следующие заголовки поддерживаются исключительно Android-версией Prizrak-Box. Они позволяют провайдерам подписок управлять отдельными элементами пользовательского интерфейса Android-клиента.

Все значения применяются при получении подписки и сохраняются в профиле до следующего обновления.

pxa-latency-dots

Управляет отображением задержки прокси в списке.

Свойство	Значение
Тип	integer
Значения	0 = числа задержки, 1 = точки задержки

Пример:

pxa-latency-dots: 1

Совместимость с Happ

Для совместимости с провайдерами, которые ранее использовали приложение Happ, также поддерживаются следующие псевдонимы:

• ping-result: time → эквивалент pxa-latency-dots: 0
• ping-result: icon → эквивалент pxa-latency-dots: 1

Если присутствуют оба заголовка, pxa-latency-dots имеет приоритет над ping-result.

pxa-simple-mode

Включает упрощённый режим интерфейса — на главном экране приложения только первую select прокси группу вашей конфигурации mihomo.

Свойство	Значение
Тип	integer
Значения	1 для включения

Пример:

pxa-simple-mode: 1

pxa-global-mode-mp

Показывает пункт меню Глобальный режим в левом нижнем углу карточки текущего профиля при запущенном подключении VPN.

Свойство	Значение
Тип	integer
Значения	1 для отображения

Пример:

pxa-global-mode-mp: 1

pxa-conns-view-mp

Показывает пункт меню Подключения в левом нижнем углу карточки текущего профиля при запущенном подключении VPN.

Свойство	Значение
Тип	integer
Значения	1 для отображения

Пример:

pxa-conns-view-mp: 1

pxa-rp-mp

Показывает пункт меню Rules Provider (RP) в левом нижнем углу карточки текущего профиля при запущенном подключении VPN.

Свойство	Значение
Тип	integer
Значения	1 для отображения

Пример:

pxa-rp-mp: 1

---

Управление интерфейсом десктопа Только десктоп

Следующие заголовки поддерживаются только десктопными версиями Prizrak-Box (Windows, macOS, Linux). Они позволяют провайдерам подписок управлять отдельными элементами интерфейса десктопного клиента.

Значение применяется при получении подписки и сохраняется в профиле до следующего обновления.

global-mode

Управляет тем, отображается ли переключатель режимов (Rule / Global / Direct) в левом боковом меню и в меню трея.

Свойство	Значение
Тип	string
Значения	false или 0 скрывают переключатель; любое другое значение (или отсутствие) показывает его

Примеры:

global-mode: false
global-mode: 0

Если значение равно false (без учёта регистра) или 0, весь переключатель режимов (Rule / Global / Direct) скрывается из левого бокового меню и из меню трея для этого профиля, если он является активным (primary, либо иначе выбранным). Любое другое значение или отсутствие заголовка оставляет переключатель видимым.

Заметка

Если в момент применения заголовка профиль находится в режиме Global, приложение автоматически возвращает активный профиль в режим Rule.

pxd-theme

Задаёт оформление десктопного клиента для профиля: фоновое изображение, прозрачность интерфейса, размытие под панелями, затемнение фона, режим (светлая / тёмная) и цвет акцента.

Свойство	Значение
Тип	string (пары ключ=значение через точку с запятой)
Кодировка	UTF-8 или Base64 (префикс base64:)
Применяется	к активному профилю (основному, либо иначе выбранному)

Параметр	Значения	Описание
image	URL (http, https)	Фоновое изображение
transparency	5–85 (%)	Прозрачность интерфейса
blur	0–30 (px)	Размытие под панелями
dim	0–80 (%)	Затемнение фона
mode	auto, light, dark	Режим оформления. auto — по фоновому изображению, без него — по системной теме
accent	#RRGGBB или auto	Цвет акцента. auto — подбирается по фоновому изображению

Все параметры необязательны. Параметр, которого нет в заголовке, берётся из настроек пользователя. Числа вне диапазона приводятся к ближайшей границе, неизвестные параметры и неверные значения игнорируются.

Изображение:

• Форматы: JPEG, PNG, WebP (рекомендуется JPEG).
• Рекомендуемый размер: около 1920×1080 и не больше ~2 МБ — изображение загружается при каждом применении темы.
• Если в ссылке есть символ ;, закодируйте его как %3B.

Полный пример:

pxd-theme: image=https://cdn.example.com/theme/bg-1920x1080.jpg; transparency=30; blur=4; dim=20; mode=dark; accent=auto

Только заданный цвет акцента и заданный режим, без изображения:

pxd-theme: mode=light; accent=#1f9e7a

В этом случае фон остаётся тем, что выбрал пользователь, а режим и цвет акцента задаёт профиль.

Тот же заголовок в Base64:

pxd-theme: base64:bW9kZT1saWdodDsgYWNjZW50PSMxZjllN2E=

Параметры, заданные профилем, показываются в разделе Тема и недоступны для изменения. Пользователь может отключить тему профиля переключателем «Тема профиля» в том же разделе — тогда возвращаются его собственные настройки. При переключении на профиль без этого заголовка также возвращаются настройки пользователя (или значения по умолчанию, если он их не менял). Если заголовок пропадёт при следующем обновлении подписки, тема профиля будет удалена.

---

HWID-аутентификация

Prizrak-Box поддерживает формат заголовков HWID Device Limit от RemnaWave. При использовании аппаратной аутентификации устройств задействованы две группы заголовков: заголовки, отправляемые клиентом с каждым запросом, и заголовки, возвращаемые сервером в ответе.

Заголовки запроса (отправляет Prizrak-Box)

Когда в профиле активен HWID, Prizrak-Box автоматически добавляет следующие заголовки к каждому запросу подписки:

Заголовок	Описание
X-Hwid	Аппаратный отпечаток — уникальный идентификатор устройства
X-Device-OS	Название операционной системы (например, Windows, Android, macOS)
X-Ver-OS	Версия ОС (например, 14, 11, 14.5)
X-Device-Model	Модель устройства (например, Pixel 8, iPhone 14 Pro Max)

Заголовки ответа (возвращает сервер)

Сервер возвращает следующие заголовки для передачи статуса HWID. Prizrak-Box читает и обрабатывает каждый из них.

X-Hwid-Active

Всегда true, когда HWID Device Limit включён на стороне сервера. Prizrak-Box использует этот заголовок для пометки профиля как HWID-защищённого в интерфейсе.

Свойство	Значение
Тип	string (булево)
Значения	true

X-Hwid-Active: true

X-Hwid-Not-Supported

true, если HWID Device Limit включён на сервере, но клиент не отправил заголовок X-Hwid. Сигнализирует приложению, что устройство не идентифицировано и подписка может быть ограничена.

Свойство	Значение
Тип	string (булево)
Значения	true

X-Hwid-Not-Supported: true

X-Hwid-Max-Devices-Reached

true, если HWID Device Limit включён и пользователь достиг максимального числа разрешённых устройств. Приложение может показать предупреждение о том, что добавить новые устройства невозможно.

Свойство	Значение
Тип	string (булево)
Значения	true

X-Hwid-Max-Devices-Reached: true

Совместимость с RemnaWave

Формат HWID-заголовков соответствует спецификации HWID Device Limit RemnaWave. Серверы подписок, реализующие формат RemnaWave, полностью совместимы с Prizrak-Box.

---

Шаблоны (PXD) Устарело

Устарело — будет удалено

Механизм заголовков Pxd-Template / Pxd-Template-Scheme устарел и будет удалён из Prizrak-Box в одном из следующих релизов.

Как работал устаревший метод можно ознакомиться здесь: How to use xhttp from Remnawave in Prizrak-Box