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

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

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

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

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

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

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

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 — приложение не придумывает пороги напоминаний самостоятельно. Если ни один из трёх заголовков не отправлен, уведомления-напоминания не показываются вне зависимости от локальной настройки «Напоминания о подписке» в приложении (эта настройка — разрешение на показ, а не источник самих порогов).

Пороги определяют только когда будет показано напоминание. Текст не равен порогу: в уведомлении указаны точные дата и время истечения (например, «Подписка истекает 05.10.2026, 14:30»), а окно, которое открывается по нажатию, пересчитывается по профилю в этот момент («истекает через 1 д 2 ч», «истекла», текущий процент использованного трафика). Поэтому напоминание, пролежавшее сутки, не скажет «4 дня», когда остались сутки.

Кнопка «Продлить подписку» (см. 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.

Управление интерфейсом мобильных версий Android и iOS

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

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

pxa-latency-dots

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

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

Пример:

pxa-latency-dots: 1

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

pxa-theme

Задаёт оформление клиента для Android, iPhone, iPad и Apple TV для профиля: цвет карточки профиля, цвет акцента, тему (светлая / тёмная) и фон главной.

Свойство	Значение
Тип	`string` (пары ключ=значение через точку с запятой)
Кодировка	UTF-8 или Base64 (префикс `base64:`)
Применяется	`card` — всегда к карточке своего профиля; `accent`, `mode`, `background` — пока профиль активный

Параметр	Значения	Описание
`card`	`#RRGGBB` или `auto`	Цвет карточки профиля: в колоде на главной, у свёрнутой карточки над активной, в открытом профиле, во вкладке «Профили» на iPad, на Apple TV. `auto` — из логотипа профиля
`accent`	`#RRGGBB`, `auto` или `user`	Цвет акцента: вкладки, кнопки, ссылки, фоны главной. `auto` — цвет карточки. `user` — как выбрал пользователь в «Цвете акцента»
`mode`	`auto`, `light`, `dark` или `user`	Тема приложения. `auto` — как в системе, `light` — светлая, `dark` — тёмная. `user` — как выбрал пользователь в «Визуале»
`background`	`topography`, `clean`, `bigGhost`, `dotGrid`, `hem`, `signal`, `ghostPattern`, `cucumber`, `mushroomia` или `user`	Фон главной. `user` — как выбрал пользователь

Все параметры необязательны. Параметр, которого нет в заголовке, берётся из настроек пользователя: по действию это то же самое, что user. Явный user говорит, что этот параметр профиль сознательно оставляет пользователю.

Ключи и значения не зависят от регистра, пробелы вокруг = и ; не учитываются. Неизвестные параметры и неверные значения пропускаются, остальное применяется. Цвет записывается только как # и шесть шестнадцатеричных цифр.

У card нет значения user: у пользователя нет своего выбора цвета карточки, она всегда берётся из логотипа, а это и есть auto.

Цвета:

Если card слишком светлый и белый текст на нём не читается, карточка затемняется, как сейчас со светлыми логотипами.
accent применяется как задан, так же как цвет из «Персонализации».

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

pxa-theme: accent=#1fb5c9; card=#0f3d4a; mode=dark; background=mushroomia

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

pxa-theme: base64:YWNjZW50PSMxZmI1Yzk7IGNhcmQ9IzBmM2Q0YTsgbW9kZT1kYXJrOyBiYWNrZ3JvdW5kPW11c2hyb29taWE=

Только цвет акцента и цвет карточки:

pxa-theme: accent=#8e5be8; card=#3b2a6b

Тема и фон остаются теми, что выбрал пользователь.

Цвет карточки, акцент по карточке:

pxa-theme: card=#c9484f; accent=auto

Только цвет карточки, остальное явно за пользователем:

pxa-theme: card=#5a2d14; accent=user; mode=user; background=user

Тема как в системе:

pxa-theme: accent=#8e5be8; mode=auto

Тема следует системе Android или iOS, даже если пользователь выбрал в приложении светлую или тёмную.

Настройки → Визуал

Если у активного профиля есть этот заголовок, сверху появляется переключатель «Тема профиля» с подписью, что задаёт профиль: «Провайдер» задаёт акцент, карточку, тему, фон. Параметры со значением user в подписи не перечисляются.
Пункты, которые задаёт профиль (Тема, Цвет акцента, Фон главной), показываются с замком и недоступны для изменения.
В «Цвете акцента» сверху плашка «Цвет задан профилем «Провайдер»». Список и «Персонализация» приглушены, выбор в них сохраняется.

Как возвращаются настройки пользователя

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

Отличия от pxd-theme (десктоп):

Нет image, transparency, blur, dim: в мобильном клиенте нет фоновой картинки и прозрачных панелей. Вместо image — background со встроенными фонами.
Добавлены card и значение user.
accent=auto берёт цвет карточки, а не цвет фоновой картинки.

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

Следующие заголовки поддерживаются только десктопными версиями 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, либо иначе выбранным). Любое другое значение или отсутствие заголовка оставляет переключатель видимым.

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`, `iOS`, `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

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

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

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

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

Ссылки

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

Объявления

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

Управление интерфейсом мобильных версий Android и iOS

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

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

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

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

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