v2RAGE для провайдеров

Как добавить пользователю вашу подписку в v2RAGE одним нажатием и какие ссылки и конфигурации принимает приложение. Описание соответствует v2RAGE 2.4.1 для iPhone, iPad и Mac из App Store. Пункты с пометкой В следующем обновлении уже сделаны и выйдут в следующей версии приложения.

Ссылка добавления подписки

Ссылка открывает v2RAGE и предлагает добавить вашу подписку:

v2rage://import?url=<адрес подписки в URL-кодировке>

url — полный адрес подписки, https:// или http://, закодированный целиком (encodeURIComponent в JavaScript). Незакодированный & из вашего собственного query разрывает адрес, и до приложения доходит только его начало.
Приложение показывает адрес и спрашивает «Добавить эту подписку?» Пока пользователь не нажал «Добавить», ничего не загружается.
При успехе пользователь видит «Подписка добавлена, серверов: N». Если в ответе нет ни одного сервера, который приложение умеет прочитать, он видит «Серверы не найдены в подписке», и ничего не добавляется.
Список подписок хранится на устройстве и синхронизируется через iCloud пользователя, если он доступен.
Повторное открытие ссылки с уже добавленным адресом заменяет прежнюю копию, второй не появляется. Регистр схемы и хоста, #фрагмент и завершающий слэш адрес не меняют.
Принимаются только адреса подписок. Ключ одного сервера (vless://…, hy2://…) в url передать нельзя: положите его в подписку или дайте пользователю вставить его на экране импорта.

Пример

Адрес подписки:

https://panel.example.com/sub/abc?format=v2ray

Ссылка:

v2rage://import?url=https%3A%2F%2Fpanel.example.com%2Fsub%2Fabc%3Fformat%3Dv2ray

Кнопка на вашей странице:

<a href="v2rage://import?url=https%3A%2F%2Fpanel.example.com%2Fsub%2Fabc%3Fformat%3Dv2ray">Добавить в v2RAGE</a>

Собрать ссылку из адреса вашей подписки

Где разместить ссылку

За кнопкой на странице https://: в личном кабинете или на посадочной странице. Нажатие в Safari открывает приложение.
Встроенные браузеры мессенджеров часто не открывают нестандартные схемы, а QR-код со ссылкой v2rage:// может не открыться из камеры. В сообщениях и QR-кодах ведите на свою https-страницу с кнопкой, а не на саму ссылку v2rage://.
Рядом с кнопкой покажите обычный адрес подписки с кнопкой копирования. Его всегда можно вставить в приложении: Настройки → Импортировать подписку.
Если v2RAGE не установлен, ссылка ничего не делает. Добавьте ссылку на App Store: apps.apple.com/app/v2rage/id6761075402.

Ручной импорт

Настройки → Импортировать подписку принимает:

адрес подписки (https://…);
ссылку одного сервера, см. Поддерживаемые конфигурации;
конфигурацию AmneziaWG: ссылку awg:// или текст файла .conf;
любое из этого с QR-кода, кнопкой «Скан QR».

Адрес подписки

Запрос

Приложение загружает подписку запросом GET с такими заголовками:

Заголовок	Значение
`User-Agent`	`v2RAGE/<версия> (build <сборка>; iOS <версия системы>)`
`x-hwid`	Идентификатор устройства для панели: 64 шестнадцатеричных символа. Одинаков во всех запросах с устройства, в том числе после переустановки приложения; на каждом устройстве свой.
`x-device-os`	Название системы, как его сообщает устройство, например `iOS` или `iPadOS`.
`x-ver-os`	Версия системы, например `18.5`.
`x-device-model`	Идентификатор модели, например `iPhone16,1`.
`x-app-version`	Версия приложения, например `2.4.1`.

Заголовки x-* следуют соглашению Happ, Remnawave и 3x-ui 3.7+: панель считает устройства по x-hwid. Если ваша панель считает устройства, отклоняйте запросы без допустимого x-hwid заголовком x-hwid-not-supported, см. Лимит устройств.

Ответ

Код 200, тело в UTF-8. Любой другой код показывается пользователю как ошибка.
Тело: по одной ссылке сервера на строку или тот же список в стандартном Base64 одной строкой, без пробелов и переносов, с паддингом = или без. В одной подписке можно смешивать протоколы.
Строки, которые приложение не умеет прочитать, пропускаются, остальные добавляются.
Как тело подписки не поддерживаются: Clash / Mihomo YAML, JSON sing-box, JSON Xray. Если ваша панель выбирает формат по User-Agent, отдавайте для v2RAGE/… обычный список ссылок.
Тело в Base64 распознаётся, только если в нём есть хотя бы одна ссылка vless://, vmess://, hysteria2:// / hy2://, hysteria://, tuic://, socks:// или socks5://. Подписку только из ссылок awg://, wireguard://, socks4://, socks4a:// или socks5h:// отдавайте обычным текстом. В следующем обновлении awg:// распознаётся и в Base64.

Заголовки ответа

Заголовок	Что делает приложение
`profile-title`	Название подписки в настройках приложения. Обычный текст или `base64:`, за которым идёт Base64 от текста в UTF-8. Без заголовка подписка называется «Subscription».
`subscription-userinfo`	`upload=…; download=…; total=…; expire=…`: трафик в байтах, `expire` в Unix-времени, в секундах. Рядом с подпиской приложение показывает дату окончания.

Имена этих заголовков отдавайте в нижнем регистре, как в таблице. Ответ целиком:

HTTP/1.1 200 OK
content-type: text/plain; charset=utf-8
profile-title: base64:TXkgVlBO
subscription-userinfo: upload=0; download=1073741824; total=107374182400; expire=1798761600

vless://11111111-2222-3333-4444-555555555555@nl1.example.com:443?type=tcp&security=reality&flow=xtls-rprx-vision&pbk=<public key>&sid=<short id>&sni=www.example.org&fp=chrome#NL%20Amsterdam

profile-update-interval читается, но для расписания не используется. На iPhone, iPad и Mac подписка загружается заново, когда пользователь обновляет список серверов или подписки в настройках. На Apple TV она обновляется и при открытии экрана серверов, не чаще раза в 15 минут.

Лимит устройств

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

Заголовок	Что видит пользователь
`x-hwid-max-devices-reached: true`	«У этой подписки исчерпан лимит устройств. Удалите ненужное устройство в панели провайдера или попросите поднять лимит.»
`x-hwid-not-supported: true`	«Панель подписки не приняла идентификатор этого устройства. Обратитесь к провайдеру подписки.»

Добавленные пользователем подписки синхронизируются через его iCloud на другие его устройства Apple с v2RAGE. Каждое устройство загружает подписку со своим x-hwid и считается отдельным устройством.

Поддерживаемые конфигурации

Ссылки серверов в подписке или вставленные по одной. Всё после # — название сервера. Чтобы задать страну сервера, начните название с флага-эмодзи или двухбуквенного кода страны (🇳🇱 Amsterdam, NL Amsterdam).

Протокол	Ссылка	Параметры
VLESS	`vless://uuid@host:port?…#имя`	REALITY: `security=reality`, `pbk`, `sid`, `sni`, `fp` (по умолчанию `chrome`); `flow=xtls-rprx-vision`. Транспорт `type`: `tcp` (по умолчанию), `xhttp` или `splithttp` (`host`, `path`, `mode`), `grpc` (`serviceName`). `security=none` без шифрования.
VMess	`vmess://` + Base64 от JSON в формате v2rayN	Транспорт TCP, с TLS или без (`tls`, `sni`, `fp`). Старая форма `vmess://method:uuid@host` не поддерживается.
Hysteria 2	`hysteria2://auth@host:port/?…#имя`, также `hy2://`	`sni` (или `peer`), `obfs=salamander` с `obfs-password`, `insecure=1`, `pinSHA256`, `up` и `down` в Мбит/с. Другие типы `obfs` не поддерживаются. Только один порт: port hopping (`443,5000-6000`) отклоняется.
Hysteria	`hysteria://host:port/?…#имя`	`auth`, `peer` или `sni`, `obfs`, `upmbps`, `downmbps`, `alpn`, `insecure`. Только UDP: `protocol=faketcp` и `wechat-video` не поддерживаются.
TUIC	`tuic://uuid:password@host:port/?…#имя`	`sni`, `congestion_control` (`bbr`, `cubic`, `new_reno`), `udp_relay_mode` (`native`, `quic`), `zero_rtt_handshake`, `alpn`, `allow_insecure` или `insecure`.
SOCKS	`socks5://[user:pass@]host:port#имя`, также `socks://`, `socks5h://`, `socks4://`, `socks4a://`	Порт по умолчанию 1080. Без TLS.
AmneziaWG	`awg://` + Base64 от файла `.conf`, также `wireguard://`; `#имя`	В подписке строками `awg://`. Текст файла `.conf` (секции `[Interface]` и `[Peer]`) можно вставить или отсканировать на экране импорта. Формат профиля Amnezia `vpn://` не поддерживается.

Правила для ссылок

У ключей с TLS явно указывайте sni: Hysteria 2, Hysteria, TUIC, VMess с TLS.
VLESS: пишите host:port?…, без / между портом и ?. Не повторяйте параметры. sni, host и остальные значения пишите без URL-кодировки; кодировать можно только path.

Не поддерживаются

NaiveProxy (naive+https://).
HTTP- и HTTPS-прокси.
Clash / Mihomo YAML, JSON sing-box и JSON Xray.
Shadowsocks и Trojan в версии 2.4.1: такие ключи отклоняются при вставке и пропускаются в подписке. См. ниже.

В следующем обновлении

Уже сделано и выйдет в следующей версии v2RAGE. До её выхода эти ключи в версии из App Store не работают.

Протокол	Что добавлено
Shadowsocks	`ss://` в форме SIP002 (данные пользователя в Base64url или открытым текстом, как требуют шифры 2022) и в старой форме целиком в Base64. Ключи с `plugin=` и ключи шифров 2022 неверной длины отклоняются.
Trojan	`trojan://` с TLS или REALITY; транспорты `tcp`, `ws`, `grpc`, `xhttp`. Не поддерживаются: `security` кроме `tls` и `reality`, отключение проверки сертификата, незнакомый `fp`. `alpn` только `http/1.1` с `ws` и `h2` с `grpc`.
VLESS	TLS без REALITY (`security=tls` с `sni`); транспорт WebSocket (`type=ws`, `host`, `path`).
VMess	Транспорты WebSocket и gRPC.

Для Shadowsocks и Trojan параметр, повторённый в одной ссылке, делает ключ отклонённым.