Редакция от 9 октября 2026 года
Здесь описано то, что клиент умеет сегодня. Разделы, помеченные «скоро», ещё не реализованы — они перечислены, чтобы было видно направление, а не чтобы по ним что-то пробовать.
Текущий выпуск клиента — 1.1.4. В таблицах у каждой строки указано, с какого выпуска она работает. «Следующий» — уже сделано, но придёт к людям со следующим обновлением: пока его нет, рассчитывать на такую строку нельзя.
Клиент разбирает семь протокольных схем, десять с учётом коротких синонимов. Схемы, которых нет в списке, он пропускает.
| протокол | схема | что это |
|---|---|---|
| vless | vless:// | VLESS, в том числе Reality |
| hysteria2 | hysteria2:// · hy2:// | Hysteria2 поверх QUIC |
| trojan | trojan:// | Trojan |
| ss | ss:// | Shadowsocks |
| vmess | vmess:// | VMess |
| socks | socks:// · socks5:// | SOCKS5-прокси |
| wireguard | wireguard:// · wg:// | WireGuard |
Ссылку на конфигурацию можно вставить в поле или из буфера обмена. Тело ответа принимается в четырёх видах: строки ссылок в base64, те же строки открытым текстом, одиночная ссылка на один сервер и JSON — массив готовых конфигураций xray или одна конфигурация объектом.
Каждая ссылка превращается в самостоятельный профиль. Локальные socks- и http-входы клиент в профиль не кладёт намеренно: незапароленный локальный socks на устройстве — это дыра.
Подпись под именем сервера («Для белых списков», «Быстрый») передаётся так же, как для Happ и INCY: параметром ?serverDescription=<base64> после имени в ссылке (#Имя?serverDescription=…) или полем meta.serverDescription в JSON. Клиент показывает её рядом с протоколом. Работает со следующего выпуска.
Выпуски до 1.1.4 включительно показывают хвост ?serverDescription=… прямо в имени сервера. Если отдаёте подпись ссылкой, смотрите на версию в User-Agent: UnlockConnect/1.1.4 и раньше её не понимают. Поле meta в JSON безопасно для всех версий — старые его просто не показывают.
Клиент понимает заголовки, которые провайдеры уже отдают для Happ, INCY и v2RayTun: настраивать панель отдельно под Unlock Connect не нужно. Все заголовки необязательны, регистр имён не важен. Текст можно передать как есть или в виде base64: и UTF-8 — так удобнее для кириллицы и эмодзи.
| заголовок | что делает клиент | с выпуска |
|---|---|---|
| profile-title | имя подписки в списке; текст или base64: | 1.1.4 |
| profile-update-interval | через сколько часов обновлять; по умолчанию час | 1.1.4 |
| subscription-userinfo | трафик и срок, формат ниже | 1.1.4 |
| subscription-auto-update-open-enable update-always | обновлять эту подписку при каждом открытии приложения, не чаще раза в минуту | следующий |
| subscriptions-sort-type sort-order | порядок серверов по умолчанию: без сортировки, по пингу, по имени. Выбор человека в приложении главнее | следующий |
subscription-userinfo передаётся одной строкой вида upload=0; download=0; total=0; expire=0 — байты и unix-время. Ноль в total означает отсутствие ограничения, ноль в expire — отсутствие срока. За три дня до срока клиент сам напоминает о продлении (со следующего выпуска; на Android — и системным уведомлением).
Значения subscriptions-sort-type — without, ping, alphabet (как у Happ); sort-order — none, ping, name (как у INCY).
| заголовок | что делает клиент | с выпуска |
|---|---|---|
| profile-web-page-url | кнопка «личный кабинет» в карточке подписки | 1.1.4 |
| support-url | кнопка «поддержка» | 1.1.4 |
| announce | текст на карточке под трафиком; текст или base64:. Следующий ответ без заголовка его снимает | 1.1.4 |
| support-email | кнопка-почта, если нет support-url | следующий |
| announce-url | нажатие на объявление открывает ссылку | следующий |
| banner-text banner-button-text banner-button-url banner-bg-color banner-button-color | инфоблок с кнопкой, как у INCY; цвета — #RRGGBB | следующий |
| sub-info-text sub-info-color sub-info-button-text sub-info-button-link | тот же инфоблок в формате Happ; цвет — red, blue или green. Если пришли оба набора, берётся banner-* | следующий |
| sub-expire-button-link | куда ведёт кнопка «Продлить» в напоминании о сроке; без неё — profile-web-page-url, потом support-url | следующий |
| hide-url hide-settings | не показывать человеку адрес подписки и QR-код | следующий |
Ссылки в кнопках принимаются только со схемами http, https и tg. Ссылка с любой другой схемой кнопку не создаёт: произвольная схема из заголовка могла бы открыть на устройстве что угодно.
| заголовок | что делает клиент | с выпуска |
|---|---|---|
| new-url | подписка переехала целиком: клиент сразу сохраняет её под новым адресом | следующий |
| new-domain | тот же путь и параметры на другом домене: домен[:порт] | следующий |
| fallback-url | запасной адрес, если основной не ответил за 9 секунд или вернул 300–599 | следующий |
Адреса переезда принимаются только по https: в ссылке подписки лежит ключ человека, и переезд на открытый http отдал бы его любому посреднику. Запасной адрес клиент хранит, пока вы не пришлёте другой, — ответ с запасного может его и не нести.
Если панель не умеет отдавать свои заголовки, их можно написать строками над списком ссылок, в формате Happ: #profile-title: Имя, #new-url: https://… — решётка без пробела и двоеточие. Понимаются все параметры с этой страницы, над base64 и внутри него. Заголовок главнее строки. Строка «# Сервер 1» с пробелом остаётся комментарием. Работает со следующего выпуска; у JSON-подписок таких строк нет.
subscription-ping-onopen-enabled — замер серверов при открытии у нас и так включён, а выключить его может только сам человек. sub-expire и notification-subs-expire — напоминание о сроке клиент показывает всегда: о том, что подписка кончается, нужно знать человеку.
С выпуска 1.1.2 каждый запрос подписки — добавление, ручное и тихое обновление — несёт заголовки устройства. Имена те же, что у Happ, Remnawave и 3x-ui, поэтому панель с лимитом устройств видит Unlock Connect без доработок.
| заголовок | значение |
|---|---|
| User-Agent | UnlockConnect/<версия>/<ОС>/<версия ОС>, например UnlockConnect/1.1.4/android/15 |
| x-hwid | идентификатор установки приложения: 10–64 символа, латиница, цифры, = и - |
| x-device-os | android, ios, macos, windows или linux |
| x-ver-os | номер версии ОС: 14.6.1, 26.5 |
| x-device-model | модель устройства, если система её сообщает; на Windows и Linux не передаётся |
Идентификатор принадлежит установке, а не железу: два разных клиента на одном телефоне — это два устройства, и переустановка приложения даёт новый идентификатор.
Чтобы отказать устройству сверх лимита, ответьте кодом 200 с пустым списком серверов и заголовком x-hwid-max-devices-reached: true или announce с объяснением. Клиент уберёт серверы этой подписки, оставит её в списке и покажет на карточке ваш текст из announce. Работает с выпуска 1.1.2.
Код 404 для этого не подходит: на ошибку клиенты, и наш тоже, оставляют прежние серверы рабочими. Заголовок x-hwid-not-supported без пустого списка отказом не считается — серверы примутся как обычно.
Ссылка со схемой unlockconnect:// открывает приложение и сразу добавляет подписку. Форм три, и различаются они не поведением, а тем, как в них лежит ваша ссылка.
| форма | кодировать ссылку | когда брать |
|---|---|---|
| unlockconnect://import/<ссылка> | не нужно | основная форма |
| unlockconnect://add/<ссылка> | не нужно | синоним import |
| unlockconnect://import?url=<ссылка> | обязательно | если удобнее параметром |
Разница существенная. В формах со слэшем ссылка берётся хвостом строки целиком, поэтому &, ? и # внутри неё доходят нетронутыми. В форме с url= ссылка разбирается как параметр запроса и обрывается на первом неэкранированном &, а всё после # теряется — молча, без ошибки. Подписки почти всегда содержат оба знака, поэтому здесь ссылку обязательно пропускать через encodeURIComponent. Если сомневаетесь — берите форму со слэшем, в ней ошибиться нечем.
Подтверждения приложение не спрашивает. Подписка загружается сразу, сверху появляется короткое уведомление об успехе или ошибке, а список серверов разворачивается на добавленном источнике — чтобы человек видел, что сработало.
Повторный переход по той же самой ссылке не создаёт дубль, а обновляет уже добавленную запись — сверка идёт по точному совпадению строки. А вот другая ссылка добавится рядом, не заменив прежнюю. Это важно, если вы выдаёте пользователю новый адрес взамен старого: сама собой старая подписка из приложения не исчезнет, попросите удалить её вручную.
Схему самой подписки приложение не проверяет — http:// принимается так же, как https://. Мы всё же рекомендуем https: конфигурация содержит ключи, и по открытому каналу их видит любой посредник. Это наша рекомендация, а не требование клиента.
Если приложение не установлено, система не сделает ничего и ничего не покажет. Запасного пути внутри диплинка нет, поэтому рядом с ним всегда держите обычную ссылку на страницу загрузки — иначе часть людей упрётся в молчание и не поймёт, что произошло.
страница загрузки — держите её рядом с диплинком
| раздел | о чём будет |
|---|---|
| Provider API скоро | конфигурация провайдера по домену подписки: название, логотип, цвета, описания серверов |
Клиент этот раздел пока не поддерживает. Как поддержит — документация придёт вместе с выпуском, а не раньше.
Список схем и заголовки сверены с кодом клиента: выпуск 1.1.4 и то, что уже готово к следующему. При расхождении документации и поведения клиента верно поведение: напишите нам, и мы поправим страницу.