Перейти к основному содержанию
Veriqa читает стандартный IConfiguration хоста, поэтому любая настройка может прийти из appsettings.json, переменных окружения, user-secrets или любого другого провайдера. Все настройки Veriqa задаются под единственным корневым ключом Veriqa: Справочник отвечает на вопрос «чем это настраивается». На соседние два вопроса отвечают отдельные страницы: что вообще поддерживается из спецификаций — Поддержка OIDC и OAuth 2.0, чего сегодня нет — Известные ограничения. В переменных окружения : превращается в __ — Veriqa:OpenIddict:Database:Provider это Veriqa__OpenIddict__Database__Provider. Здесь стоит знать про одно ограничение оболочки. В имени переменной POSIX-оболочка допускает только буквы, цифры и _, поэтому export отвергает имя целиком, как только - или . содержит любой сегмент пути: export Veriqa__ChannelDisplay__Hints__my-channel=... отклоняется как недопустимый идентификатор. Откуда взялся такой сегмент, роли не играет. Это может быть значение, которое выбираете вы: тип канала в Veriqa:AuthPageDesign:QrCode:PixelsPerModuleByChannel:<тип канала> и в Veriqa:ChannelDisplay:Hints:<тип канала> (типу канала SPI-адаптера дефис разрешён) или код записи в каталоге Veriqa:UiConfigurations:Records. Ровно так же это может быть фиксированное имя ключа схемы, которое вы не выбираете вовсе, — вид сообщения в Veriqa:MessageTemplates:confirmation-prompt. Само имя переменной при этом законно, и ограничение обходится штатными средствами: Docker (-e), переменные Kubernetes (env:), launchSettings.json и вызов env ИМЯ=ЗНАЧЕНИЕ команда такие имена принимают, а .NET читает их как обычно. Путь, все сегменты которого состоят из букв, цифр и _, задаётся переменной окружения обычным порядком. Отдельный каталог конфигурации. Одна переменная задаёт не настройку, а место, откуда настройки читать: VERIQA_CONFIG_DIRECTORY указывает на каталог, и найденные там appsettings.json и appsettings.<Environment>.json хост накладывает поверх файлов, поставляемых с программой, и под переменными окружения. Оба файла необязательны; несуществующий каталог останавливает старт, пустой ошибкой не является. Так хранит свою конфигурацию установка службой ОС — /etc/veriqa на Linux, %ProgramData%\Veriqa на Windows, — там её не заденет замена программы.
Конфигурация валидируется на старте. Неизвестное значение enum, реляционный провайдер без строки подключения или включённый канал без токена останавливают приложение сразу на старте, а не на первом входе пользователя.

Veriqa:OpenIddict

OIDC-сервер, его хранилище и зарегистрированные клиенты.

Database

Умолчания у Provider нет: незаданное значение — не «InMemory по умолчанию», а несделанный выбор. Вне окружения Development такой хост не стартует (проверка на старте называет лечение), в Development — поднимается с Warning. InMemory остаётся допустимым значением, но задаётся явно, и каждый перезапуск инвалидирует выданные токены — подходит для разработки и для коннектора на одном инстансе. Во встроенном режиме эти ключи провайдер не выбирают — там его выбирает ваш хост вызовом authServer.UseOpenIddictDatabase(...) либо authServer.UseInMemoryOpenIddictStore(); в self-hosted-режиме выбор задаётся этими ключами.

Server

Поведение зависит от окружения:
  • Development — без явных сертификатов генерируются dev-ключи. Удобно локально, но каждый перезапуск даёт новые ключи, и несколько инстансов их не разделяют.
  • Любое другое окружение — dev-ключей нет: сервер не стартует, пока не заданы оба сертификата (подписи и шифрования). Отката на автогенерацию не существует.
Готовый Docker-образ запускается с ASPNETCORE_ENVIRONMENT=Production, то есть под второе правило. Если вы видите сгенерированные dev-ключи в развёрнутой установке — значит процесс поднят в Development: исправьте это до запуска в продакшн.

Clients

Veriqa:OpenIddict:Clients — массив приложений, которым разрешено выполнять вход: Рядом с массивом клиентов — гейт развёртывания:

Veriqa:TransactionEngine

Жизненный цикл транзакции входа.

Store

Про миграции и ретенцию — см. Хранилища.

Veriqa:ScopesClaims

Какие scope’ы существуют, какие claim’ы они несут и какие claim’ы требуются для входа.
Непустой Scopes замещает собственный набор scope’ов продукта целиком: scopes_supported discovery-документа перечисляет ровно scope’ы каталога (плюс openid, который регистрируется всегда), а запрос любого другого scope отклоняется с invalid_scope. Если ваши клиенты используют offline_access, channel или avatar, перечислите их в каталоге явно.
Ключи claim в Claims:

Veriqa:AuthPageDesign

Внешний вид страницы входа — полный разбор в Конфигурации и кастомизации. ChannelButton, ChannelLayout и Cancel задаются на тех же уровнях владения, что секция QrCode ниже: запись ui_config → клиент (Veriqa:OpenIddict:Clients[]) → тенант → эта глобальная секция, — и ближайший уровень, задавший ключ, выигрывает его отдельно от остальных. У RememberChannel уровня ui_config нет: он задаётся у клиента, у тенанта и в этой глобальной секции.

Veriqa:AuthPageDesign:QrCode

QR-код на странице входа: показывать ли его и в каком разрешении рисовать. Секция задаётся на четырёх уровнях владения, и побеждает ближайший заданный: запись ui_config → клиент (Veriqa:OpenIddict:Clients[].QrCode) → тенант → эта глобальная секция. Показ QR-кода и разрешение — две разные настройки, и уровень выигрывает каждую отдельно: клиент, задавший только ShowQrCode, оставляет разрешение глобальным. Разрешение при этом — одна настройка, заданная по каналам: PixelsPerModuleByChannel и PixelsPerModule — две записи одного и того же уровня, и уровень исчерпывает их обе, прежде чем разрешение начнёт искаться уровнем ниже. Практическое следствие: клиент, задавший только PixelsPerModule, выигрывает разрешение для всех каналов — карта по каналам из глобальной секции до него не доходит. Чтобы у канала осталось своё разрешение, назовите его в карте того же уровня, который задаёт PixelsPerModule. Пример. Глобальная секция задаёт PixelsPerModule: 6 и PixelsPerModuleByChannel с записью telegram: 14, а клиент app-client — только PixelsPerModule: 8: PixelsPerModule вне диапазона на уровне клиента или записи ui_config не применяется — разрешение приходит с уровня ниже, старт не останавливается. Про такое значение сообщает одно предупреждение в логе на снимок конфигурации: весь каталог значений (глобальная секция, записи клиентов, записи ui_config) проверяется при старте и при каждой перезагрузке конфигурации, а не на каждый запрос. В глобальной секции такое значение остаётся ошибкой развёртывания и останавливает старт.

Veriqa:Localization и Veriqa:ChannelDisplay

Veriqa:RateLimit

Лимиты по группам эндпоинтов: каждый задаёт число разрешений за окно в секундах. Значения по умолчанию: Значения по умолчанию рассчитаны на сайт с 1000 пользователей. Маршруты каждой группы, допущения расчёта и пересчёт под ваше число пользователей описаны на странице Лимиты запросов под ваш трафик. Лимиты вебхуков заслуживают внимания при масштабировании: они применяются на инстанс, и провайдер канала, который часто повторяет запросы, может их исчерпать. Лимит Webhook считается отдельно для каждого сегмента тенанта в адресе вебхука, а у адреса без сегмента — свой счёт, поэтому трафик одного тенанта не расходует лимит другого. WebhookMaxPartitions ограничивает, сколько сегментов считается отдельно в пределах одного окна; запросы с новыми сегментами сверх этого числа делят один общий счёт. Значение ноль или меньше останавливает хост на старте.

Veriqa:CodeStart

Настройки старта по коду у каналов, которые его объявили. Ключи читаются только из конфигурации хоста. Значение вне границ — длина вне 6…10, лимит или окно ноль и меньше — останавливает хост на старте.

Veriqa:InitiatorContext

Контекст об устройстве, начавшем транзакцию, показываемый пользователю до подтверждения — см. Контекст инициатора.
Offline-путь GeoIP ожидает базу GeoLite2, которую Veriqa не поставляет. Скачайте её у MaxMind сами и примите их EULA — библиотека Apache-2.0, лицензия лежит на данных. В standalone-образе библиотека уже есть: смонтируйте базу и задайте GeoIp:DatabasePath, чтобы её включить. В свой хост её подключает сателлитный пакет Veriqa.Core.AuthServer.MaxMind (builder.Services.AddMaxMindGeoIp()).

Veriqa:HopMode

Hop-режим кладёт в QR-код короткую одноразовую ссылку на ваш сервер Veriqa вместо ссылки канала. Две его настройки задаются на весь узел и могут быть переопределены для отдельного канала: Заданное значение канала побеждает значение узла; отсутствующее или пустое — наследует его. Остальные ключи HopMode.* и их значения по умолчанию — в разделе Ключи в каталоге объявлений, где у HopMode.Enabled и HopMode.RedirectStyle стоит «not declared»: их значения по умолчанию — значения выше. Один QR-код на всю транзакцию. Veriqa:HopMode:QrMode решает, что показывает окно входа или страница подтверждения с несколькими каналами, пока hop-режим включён хотя бы для одного из них: Страница с одним каналом, страница при ShowQrCode: Never и телефон при DesktopOnly вкладок не показывают при любом значении. В окне компьютера, достаточно широком для этого, страница с одним QR-кодом раскладывается в две колонки: слева QR-код, справа кнопки каналов. Окно поуже и страница, не показывающая кнопок каналов на компьютере (ShowChannelButton: MobileOnly или Never), остаются в одну колонку. Veriqa:HopMode:ShowChannelButtonsOnAnyChannelTab (по умолчанию true) при UnifiedWithChannels решает, показывает ли вкладка «Любой канал» кнопки каналов рядом с одним QR-кодом. При false на этой вкладке остаётся только QR-код, а её инструкция просит лишь отсканировать его; вкладка каждого канала свою кнопку сохраняет. Телефон при ShowQrCode: DesktopOnly QR-кода не показывает, поэтому кнопки всех каналов на нём видны при любом значении. При PerChannel и Unified ключ ни на что не влияет.
Hop-режим рекомендуем включать. Пользователю с ним удобнее: лёгкий QR-код, который камера любого телефона читает сразу, сигнал «отсканировано» на странице компьютера, как только телефон открыл ссылку, и страницу запуска там, где прямой переход в приложение мессенджера ненадёжен. По умолчанию он выключен по одной причине: каждая hop-ссылка строится на Veriqa:OpenIddict:Server:Issuer, поэтому при включённом hop issuer должен быть задан абсолютным адресом https, иначе сервер не стартует. Ещё этот адрес должен быть доступен телефону — чтобы попробовать hop-режим на своей машине, выставьте Veriqa через HTTPS-туннель, см. Локальная проверка интеграции. Чем hop-режим лучше — на странице Hop-режим.
Канал Email в hop-режиме. Цель канала Email — письмо, которое открывает сам телефон, поэтому его hop-ссылка ведёт в него же, как и ссылка без hop-режима. RedirectStyle действует на Email так же, как на любой другой канал. Direct сразу перенаправляет в письмо (302 на mailto:), и строку «письмо открыто в почтовом приложении» окно входа получает от самого перенаправления. Interstitial даёт страницу, которая сама открывает письмо и держит кнопку на случай, если оно не открылось: при включённом входе по ссылке из письма (PullEnabled) на ней есть ещё ссылка на форму адреса, при выключенном это страница запуска, как у любого канала. См. Email в hop-режиме.

Hop-режим для одного приложения

Те же члены можно задать внутри записи OIDC-клиента (Veriqa:OpenIddict:Clients) — тогда они действуют только для этого приложения:
appsettings.json
Для каждого канала значение берётся в таком порядке: значение канала в записи клиента → общее значение записи клиента → узел (его значение канала, затем значение на весь узел). Запись клиента, которая ничего не задала, наследует узел. Значение, которое не удаётся прочитать, — "HopEnabled": "maybe" или имя стиля, отличное от Interstitial / Direct, — пропускается с предупреждением в журнале, и действует следующее значение в этом порядке. Стиль, заданный числом, за которым не стоит ни один из двух, пропускается так же, но без предупреждения. Остальные настройки hop в записи клиента не задаются. TokenLifetime и переключатели — что собирается о сканирующем устройстве, EmitScannedStatus, AcceptClientSignals, WarnOnRepeatScan — задаются на узел, а запись тенанта может только выключить переключатель или сократить срок. HopPath задаётся только на узел. Эндпоинт, на который ведёт hop-ссылка (HopPath), существует, только если на старте hop-режим включён для канала, включённого на узле, — на весь узел, для этого канала либо хотя бы в одной записи клиента. Исключение — канал со стартом только по коду: если такой канал объявлен в хосте и включён, эндпоинт есть и при выключенном hop-режиме, см. Старт по коду. Записи клиентов читаются один раз при старте: если hop-режим был выключен везде и вы включаете его в записи клиента — перезапустите хост. При включённом hop-режиме Veriqa:OpenIddict:Server:Issuer обязан быть абсолютным https-URL — и когда режим включён в записи клиента, и когда на узле.

Инфраструктура

Плоские ключи, читаемые хостом, в основном актуальны при запуске более одного инстанса или за прокси: Если не задан ни один вариант хранения DataProtection, ASP.NET Core держит ключи в своём расположении по умолчанию для учётной записи, под которой работает хост; в образе контейнера оно внутри контейнера и пропадает, когда контейнер пересоздаётся. Для разработки это подходит, для продакшна и нескольких инстансов — нет. Чтобы сменить сертификат, перенесите текущий в ключи Previous* и задайте новый: новые ключи шифруются новым сертификатом, а зашифрованные старым остаются читаемыми. Внутри вашего приложения Veriqa использует его кольцо и ключи Veriqa:DataProtection:* не читает.
Лицензирование Redis. Redis server ≥ 7.4 поставляется под RSALv2/SSPL (8.x дополнительно предлагает AGPL). На лицензию Veriqa это не влияет, но если влияет на вашу политику — Valkey (BSD) заменяет его без доработок.

Veriqa:Channels

Каждый канал настраивается в секции Veriqa:Channels:{Channel} и активируется только с "Enabled": true. Полная настройка с шагами на стороне провайдера — в Настройке каналов. Ещё два ключа можно добавить в секцию любого канала, включая канал стороннего адаптера: SpareStartCodeEnabled (bool, по умолчанию true) включает запасной код, который страница входа предлагает для канала с рабочей ссылкой, а BotName (текст, по умолчанию не задан) задаёт имя, под которым пользователь видит чат, — оно старше имени, которое сообщает сам канал. Оба — ключи ядра с каналом-измерением, Channels.SpareStartCodeEnabled и Channels.BotName в каталоге, задаются в конфигурации хоста либо для тенанта. Что они меняют на страницах: Настройка каналов.

Режимы входа по Email для одного приложения

PullEnabled и PushEnabled секции Veriqa:Channels:Email задают, какие режимы входа обслуживает установка, а PreferredMode — какой из них страница входа предлагает первым. Тенант и приложение выбирают из обслуживаемых режимов двумя членами своей записи и не могут добавить режим, которого установка не обслуживает. Ещё два члена задают, что несёт письмо входа:
appsettings.json
Если установка обслуживает оба режима, portal предлагает форму адреса для magic link и не предлагает письмо в один тап; приложение без этого члена сохраняет оба режима. Запись тенанта задаёт те же члены. В каталоге это ключи Channels.email.SignInModes, Channels.email.PreferredMode, Channels.email.PullMethods, Channels.email.SignInCodeAttempts, Channels.email.SignInMailsPerAddress и Channels.email.SignInMailsPerDomain. Вход предлагает режимы установки, суженные сначала тенантом, затем приложением. Предпочтённый режим вне этого набора не действует: вход предлагает оставшийся в наборе режим. Подтверждение, которое создаёт ваш сервер, предлагает те же режимы, что и вход клиента, который его создал. Где документация описывает, что показывает вход при включённом Pull или Push, имеется в виду, что режим есть в этом наборе: по нему работают окно входа, страницы hop и форма адреса /auth/email/start. Входу без Pull форма адреса отвечает 503 — так же, как при PullEnabled: false. Ключи секции Enabled, PullEnabled и PushEnabled Veriqa читает при старте хоста, поэтому после их изменения перезапустите хост. Выбор касается только того, как начинаются вход и подтверждение. Письма, которыми Veriqa получает недостающий email при доборе claims, зависят от того, что обслуживает установка (PullEnabled), поэтому приложение, которое предлагает только Push, их тоже получает. Так же от секции зависит приём писем в один тап. Пустого выбора нет. Список, записанный пустым или не называющий ни одного режима уровня выше, пропускается, и действуют режимы этого уровня. Если список не называет ни одного режима, который обслуживает установка, — ["Push"] при одном Pull или [], — Veriqa пишет в журнал предупреждение с именем записи клиента на старте и при перезагрузке конфигурации. Список с именем режима, отличным от Pull и Push, пропускается так же. Список не выключает Email: канал включает и выключает Enabled секции, а клиент сужает каналы своих входов параметром acr_values — см. Как дать клиенту выбрать канал.

InboundVerification — обязательный ключ каждой канальной секции

Veriqa:Channels:{Channel}:InboundVerification объявляет, как проверяется подлинность входящего события этого канала. Значение выбирается из закрытого словаря:
Ключ обязателен для каждого включённого канала. Развёртывание, где включён канал, объявленный на уровне ядра ("Enabled": true), а значение не задано или не входит в словарь, не стартует: сообщение назовёт тип канала, адрес ключа и все четыре допустимых токена. Значение стоит проставить и в секциях выключенных каналов — тогда переключение Enabled в true не остановит старт. Стартовая проверка перебирает ровно тот набор каналов, из которого ядро строит список включённых: все поставляемые каналы в нём есть, а канал, подключённый через SPI одним вызовом AddChannel, в него не попадает — ключ в его секции тоже нужен, но без него старт не остановится, см. Свой канал на C#.
Факт объявляете вы, а не адаптер и не ядро: Veriqa видит только то, что проверка выполнилась и прошла, но не то, чем именно она была, — а вывод значения по типу канала означал бы, что сторонний канал описать нечем. Значение для каждого встроенного канала и режима — в Настройке каналов. Канал, забирающий обновления сам (UpdateMode: Polling), но объявивший что-то кроме outbound_fetch, даёт Warning при старте — старт при этом продолжается. Объявленное значение попадает в запись журнала аудита отдельным атрибутом, поэтому по журналу видно, чем было защищено подтверждение.

OutcomeNotice — где появляется квитанция исхода

Veriqa:Channels:OutcomeNotice:DisplayIntent (ключ Channels.OutcomeNotice.DisplayIntent) говорит, как вы хотите видеть квитанцию терминального исхода в переписке. Значение задаётся на трёх уровнях — ядра, тенанта и приложения, — и каждый свободно перекрывает нижний: глобальная секция задаёт намерение всей установки, тенант — своё, членом OutcomeNoticeDisplayIntent своей записи, отдельное приложение — членом с тем же именем в своей записи OIDC-клиента. Запись ui_config намерения не задаёт. Какой бы уровень ни ответил, значение действует на исход целиком — подтверждение, отказ и истечение показываются одинаково. Поставочное значение — ReplacePrompt: ровно то, что каналы делали до появления настройки, поэтому развёртывание, которое ничего не задало, изменения не увидит. Нечитаемое значение читается как незаданное и отвечает тем же ReplacePrompt; старт при этом не прерывается.
Это намерение, а не гарантия. MAX и Telegram его исполняют. WhatsApp, Instagram*, Messenger*, WeChat и Viber всегда отправляют новое сообщение, а Email квитанцию исхода не показывает вовсе — так они устроены в сегодняшней поставке. Адаптер, не исполнивший намерение, не ошибается: ошибка не пишется в журнал, результат доставки не меняется. При NewMessage квитанция приходит отдельным сообщением, а кнопки вопроса снимаются тем же ходом — там, где платформа умеет сменить кнопки сообщения, не переписывая его текст; формулировка вопроса при этом не переписывается никогда. Неудача снятия доставку тоже не ломает — и если кнопка уцелела, повторное нажатие принесёт ещё одну квитанцию, потому что терминальную транзакцию переиграть нельзя.

InboundDeduplication — повторная доставка входящего события

Платформа мессенджера иногда доставляет одно событие дважды почти одновременно: например, повторяет вебхук, не дождавшись ответа на первую доставку. Чтобы пользователь не получил в чате два одинаковых вопроса, Veriqa не обрабатывает повтор события, принятого в пределах короткого окна. Длину окна задаёт Veriqa:Channels:InboundDeduplication:Window — промежуток в формате TimeSpan:
Поставочное значение — 500 мс (00:00:00.5). 00:00:00 выключает отбор повторов, отрицательное значение останавливает старт хоста. Ключ действует на всю установку: тенант и приложение его не переопределяют. Ключ Veriqa читает при старте хоста, поэтому после его изменения перезапустите хост. После окна такое же событие Veriqa обрабатывает как новое: если пользователь снова переходит по ссылке, пока транзакция не завершена, вопрос придёт ещё раз. Нажатия пунктов меню окно не отбрасывает: повторная доставка нажатия доходит до вашего IMenuItemPressHandler с тем же PressId, и повтор вы отбрасываете по нему.
Отбор повторов работает внутри одного экземпляра. Принятые события Veriqa помнит в памяти процесса. Если экземпляров несколько, повтор, который балансировщик отдал другому экземпляру, будет обработан там.

Veriqa:LoginConfirmation

Где Veriqa задаёт пользователю вопрос о входе или о подтверждении — в чате или на странице Veriqa. Режим задаётся сразу для всех каналов или для канала отдельно. None действует только на вход: подтверждение всегда спрашивает пользователя, и для него None читается как ChannelDefault. InChannel у канала, который не умеет спрашивать в чате, — у Email или у стороннего канала, который этого не объявил, — применяется как OnWebPage, а в лог уходит предупреждение. Значение, которого настройка не принимает, старт не прерывает: число, не называющее режима, отбрасывает только ту запись, в которой стоит, а текст, не совпадающий ни с одним режимом, оставляет незаданным весь уровень. Режим задаётся на трёх уровнях владения, и побеждает ближайший уровень, который его задал: клиент → тенант → эта глобальная секция. В записи клиента два члена называются LoginConfirmationMode и LoginConfirmationModeByChannel, запись тенанта задаёт ту же пару. Запись ui_config режима не задаёт: место вопроса — политика безопасности, а не оформление. ModeByChannel и Mode — две записи одного и того же уровня, и уровень исчерпывает их обе, прежде чем режим начнёт искаться уровнем ниже. Поэтому клиент, задавший только LoginConfirmationMode, решает режим для всех каналов, и до карты глобальной секции дело не доходит. Чтобы сохранить режим канала, назовите его в карте того же уровня.
appsettings.json
Здесь вход через Email завершается, как только владение ящиком доказано, а вход через любой другой канал спрашивает на странице Veriqa.
При None достаточно открыть ссылку. Многие корпоративные почтовые шлюзы и почтовые клиенты открывают ссылки во входящих письмах, чтобы проверить их, и при None такое открытие завершает вход того, кто его начал. Тот, кто введёт адрес вашего пользователя в окне входа, войдёт под этим пользователем, как только шлюз проверит письмо или сам пользователь из любопытства откроет ссылку. По умолчанию открытие ссылки вход через Email не завершает: пользователь подтверждает его сам. Включайте None для Email только в исключительных случаях — в тестовых окружениях и приложениях с низким риском, где чужой вход не причинит вреда.

Veriqa:CompletionBehavior

Что канал делает после завершённого входа. Это одно действие, заданное сразу для всех каналов или для канала отдельно, и — для действий с кнопками — сами кнопки. Действие задаётся на трёх уровнях владения, и побеждает ближайший уровень, который его задал: клиент → тенант → эта глобальная секция. Выше глобальной секции те же члены лежат в секции CompletionBehavior собственной записи уровня — для приложения это Veriqa:OpenIddict:Clients[].CompletionBehavior:Action и …:ActionByChannel. Запись ui_config действия не задаёт: это поведение, а не оформление. Поставочное значение — None, поэтому развёртывание, которое ничего не задало, изменения не увидит. Значение, которого настройка не принимает, старт не прерывает, а как далеко оно действует — зависит от его вида. Текст, не совпадающий ни с одним именем настройки, — в Action или в записи ActionByChannel — оставляет незаданным весь уровень: ни один из двух его членов не читается, и действие приходит с уровня ниже. Число, не называющее действия, отбрасывает только ту запись, в которой стоит: при Action: "WelcomeMessage" и ActionByChannel: { "telegram": 7 } на одном уровне telegram получает WelcomeMessage этого уровня. Действие — одна настройка, заданная по каналам: ActionByChannel и Action — две записи одного и того же уровня, и уровень исчерпывает их обе, прежде чем действие начнёт искаться уровнем ниже. Поэтому клиент, задавший только Action, выигрывает действие для всех каналов — карта по каналам из глобальной секции до него не доходит. Чтобы у канала осталось своё действие, назовите его в карте того же уровня, который задаёт Action.
Здесь за входом через telegram следует приветственное сообщение, а за входом через любой другой канал — ничего. Что канал исполняет — факт самого канала, а не вашей конфигурации: Действие, которого канал не исполняет, ему не передаётся. Оно заменяется собственным действием канала по умолчанию — None, если канал не объявил другое, как может HTTP-канал ключом Http:Capabilities:DefaultCompletionBehaviorAction, — и замена громкая: Warning в журнале и событие аудита channel_completion_behavior_clamped, в деталях которого записано requested=<действие>; applied=<действие>. Сам вход завершается как обычно. Запись аудита называет тенанта и клиента входа — уровни, на которых действие могло быть задано, — а её актор — маскированный пользователь канала. Запись несёт исход «неуспех», как любое событие канала, хотя вход прошёл успешно. None не заменяется никогда: «ничего не делать» исполняется на любом канале, молча. whatsapp с провайдером Twilio объявляет те же действия, но отправляет только приветствие: Menu и Redirect не заменяются, их отправка завершается ошибкой: Veriqa пишет её в журнал, а в чат не приходит ничего. Menu и Redirect отправляют сообщение: текст и кнопки под ним. Redirect — одна кнопка, открывающая ссылку; Menu — список кнопок в том порядке, в котором вы их задали. Каналы, которые их исполняют, перечислены в таблице выше; на любом другом канале действие заменяется, как описано там же. Кнопки каждый канал отрисовывает средствами своей платформы:
Здесь за входом через max или telegram следует меню из двух кнопок: первая открывает ссылку, нажатие второй передаётся вашему коду. Для перенаправления достаточно адреса — подпись поставляется как Open:
Пункты и адрес задаются так же, как действие. MenuItems и RedirectUrl живут на тех же трёх уровнях, каждый — рядом со своей картой по каналам, и уровень исчерпывает карту и простой член, прежде чем читается уровень ниже: клиент, задавший только RedirectUrl, выигрывает адрес для всех каналов. RedirectButtonText — одно значение на уровень, карты по каналам у него нет. Запись ui_config не задаёт ни одного из них. Подписи переводятся, адрес не трогается. Text пункта и RedirectButtonText ищутся в locale-файлах вашего хоста на языке получателя; подпись, которой нет ни в одном файле, показывается так, как вы её написали. Адрес уходит ровно таким, каким задан: ничего о пользователе в него не подставляется. Текст над кнопками — отдельное сообщение вида post-login-menu либо post-login-redirect: формулируется и переопределяется как любое другое сообщение — Veriqa:MessageTemplates. Что делает пункт ссылкой. Action, записанный абсолютным URL со схема:// в начале — https://…, tg://…, — становится кнопкой-ссылкой. Любое другое значение — callback data: кнопка присылает его обратно при нажатии. Тем же правилом проверяется RedirectUrl. Поэтому адрес без // — mailto:…, tel:… — читается как callback data, а не как ссылка. Значение с пробелом или переводом строки по краю не принимается вовсе — ни как RedirectUrl, ни как Action: о нём сообщается как о любом значении вне домена настройки, а из-за пункта, записанного так, отбрасывается весь список этой записи. Допустима ли схема на кнопке, решает платформа: адрес, который она отклонила, срывает отправку, и сообщение не уходит. Ссылка может нести handle связки. Запишите {handle} — именно в этом регистре — в RedirectUrl, в значение RedirectUrlByChannel или в Action пункта-ссылки, например https://t.me/shop_bot?start={handle}. При отправке сообщения каждый {handle} в его адресах заменяется одним одноразовым значением из 22 символов [0-9A-Za-z]; ваш сервер меняет его на идентичность вошедшего пользователя — Два бота. На сообщение выпускается один handle, он действует Veriqa:TransactionEngine:CompletedRetentionSeconds с момента выпуска. Адрес без плейсхолдера уходит как записан, handle не выпускается; отдельной настройки, включающей подстановку, нет. В callback data {handle} не заменяется — значение уходит как записано. Если handle выпустить нельзя — вход не относится ни к одному клиенту либо хранилище handle отказало в записи, — кнопки с плейсхолдером не отправляются, пишется Warning: Redirect не отправляет ничего, Menu уходит без таких пунктов. На вход это не влияет. Callback-пункт передаётся вашему коду. Нажатие приходит в адаптер канала — встроенный или внешний адаптер HTTP-канала, который отправляет его в Veriqa событием menu_item_pressed, — и передаётся обработчику, который вы зарегистрировали:
IMenuItemPressHandler и MenuItemPress приходят с пакетом Veriqa.Core.Contracts. Обработчик ничего не возвращает: если платформа ждёт ответа на нажатие, ей отвечает адаптер (встроенный — ещё до вызова обработчика, на HTTP-канале — внешний адаптер), а что нажатие значит, решает ваш код. Входа событие не называет: меню показано после того, как вход завершён. Обработчик создаётся в момент нажатия пункта, в скоупе этого события, и ни для какого другого события канала. Исключение — брошенное его конструктором или методом HandleAsync — пишется в журнал и не влияет ни на пользователя, ни на вход. Возвращайтесь быстро. HandleAsync ожидается, пока обрабатывается событие. Пока он не вернулся, платформа не знает, что событие принято: вебхук, оставшийся без ответа, доставляется повторно, и обработчик получает то же нажатие дважды; в режиме polling за ним ждут события других пользователей. Долгую работу переносите в собственную фоновую очередь и сразу возвращайте управление. Повторное нажатие отбрасывайте по press.PressId. Veriqa повторы нажатий не отбрасывает: нажатие, доставленное ещё раз, снова доходит до обработчика с тем же PressId. У встроенного канала это идентификатор, который платформа даёт нажатию: id callback-запроса у telegram, callback_id у max, id сообщения (wamid) у whatsapp, mid из postback у messenger и instagram, message_token у viber, MsgId у wechat. У HTTP-канала это webhook-id события. Если работа обработчика не должна выполниться дважды, привяжите её к PressId; null — канал идентификатора не назвал. PressId уникален только в пределах одного канала: если хост обслуживает несколько каналов, составляйте ключ из press.ChannelType и PressId. Считайте press.Value недоверенными данными. Кнопка переживает конфигурацию, которая её нарисовала: пункт, убранный из MenuItems, по-прежнему нажимается в старом сообщении, и со списком пунктов, заданным сегодня, Veriqa значение не сверяет. Проверяйте значение — и то, что этому пользователю разрешено, — в своём обработчике. На HTTP-канале press.ChannelUserId заявляет внешний адаптер, которому доверяет оператор, а не платформа. press.TenantId задаёт Veriqa: это тенант, которого называет Http:Tenant, а если он не задан — тенант маршрута, на который адаптер отправил событие. Нет ни того ни другого — null. Без зарегистрированного обработчика callback-пункты не отрисовываются. Warning называет, сколько их пропущено; пункты-ссылки того же меню уходят. Нажатие кнопки, отправленной до перезапуска, после которого обработчика не стало, остаётся без обработки. Когда ничего не отправляется. Menu без пунктов, заданных для канала, Menu, все пункты которого пропущены, и Redirect без заданного адреса пишут Warning и ничего не отправляют; вход завершается как обычно. Значение, которого настройка не принимает, старт не прерывает и оставляет свою запись незаданной — значение приходит из следующей записи или с уровня ниже: это RedirectUrl, который не является URL, и список, в котором у любого пункта пуст Text или Action, — из-за одного такого пункта отбрасывается весь список этой записи. Пустой список тоже ничего не задаёт: чтобы выключить меню уровнем выше, задайте Action, а не пустой список. Бюджет платформы проверяется до отправки — по лимитам, которые платформа называет сама: У max, instagram, viber и wechat лимит payload заранее не проверяется, и значение, которое платформа отклонила, срывает всё сообщение. У telegram, whatsapp и messenger слишком длинное значение убирает только одну кнопку. Держите значения callback-пунктов короткими. Сообщение, в котором не осталось ни одной кнопки, не отправляется. Как ведёт себя сообщение пост-действия — и приветственное, и сообщение с кнопками:
  • Оно следует за каждым завершённым входом через канал, который исполняет действие, — вход подтверждён в канале, на веб-странице либо завершён шагами добора недостающих claims. Подтверждение, которое создаёт ваш сервер, входом не является, и за ним не следует ничего.
  • Оно приходит отдельным сообщением, после квитанции исхода, и никогда её не заменяет.
  • Сбой отправки пишется в журнал и результат входа не меняет.
  • Текст приветствия — вид сообщения post-login-welcome: формулируется, переводится и переопределяется как любое другое сообщение — Veriqa:MessageTemplates.
  • Факт доставки на транзакции не записывается. Событие, повторённое по порядку, второго сообщения не даёт; одно и то же событие, обработанное дважды в один момент, в сегодняшней поставке может.
В таблице каталога у ключа CompletionBehavior.Action в столбце «По умолчанию» стоит не объявлен: поставочное None применяется там, где действие не задал ни один уровень, — так же, как поставочное разрешение у AuthPageDesign.QrCode.PixelsPerModule. У CompletionBehavior.MenuItems и CompletionBehavior.RedirectUrl там же не объявлен по более простой причине: ни меню, ни адреса продукт не поставляет.

Veriqa:MessageTemplates

Всё, что пользователь читает в мессенджере и в письме, — сообщения. Одно сообщение — это две настройки, а не одна текстовка: контракт объявляет, какие слоты у сообщения есть, а шаблон несёт формулировки, которые этими слотами пользуются. Поэтому и адресов два — на сообщение, а не на каждый текст: Группы в квадратных скобках необязательны: формулировка, которая не сужается по оси, опускает её группу целиком — так один адрес обслуживает все шаги подстановки, от самого специфичного ({вид, тип транзакции, тип действия, поверхность, канал, назначение ссылки, тип устройства}) до самого общего ({вид}). Вид сообщения из группы не выпадает никогда: «текст какого сообщения» — это и есть сам вопрос. Одна группа не самостоятельна: ByAction читается только внутри ByType. Ни один шаг подстановки не называет тип действия без типа транзакции, поэтому формулировка по адресу {вид}:ByAction:{тип действия} недостижима — хост на ней не стартует с сообщением, что адрес «narrowed by a combination of axes no step of its ladder addresses». Тип действия подтверждения поэтому формулируется по адресу {вид}:ByType:confirmation:ByAction:{тип действия}. Виды, которые везёт поставка: Значение шаблона — лестница ступеней от самой полной к минимальной, одним массивом. Ступень — это либо строка (текст, годный любому приёмнику), либо структура { "Subject": "…", "Html": "…", "Plain": "…" }, где Html и Plain — редакции ступени: письмо формируется одно и несёт обе части сразу. Каждая редакция необязательна, но ступень обязана заявить хотя бы одну — иначе отказ на старте с указанием рода сообщения и номера ступени. Показывается первая ступень, заявившая запрошенную редакцию и все слоты которой заполнены; поэтому две части одного письма могут прийти с разных ступеней, а тема берётся у ступени, выбранной для Html. Редакцию, которую не заявила ни одна ступень, письмо не несёт вовсе — так объявляется «письмо только в html». Минимальная ступень обязана опираться только на гарантированные слоты — это проверяется на старте, на каждом шаге и по каждой редакции отдельно. Шаг, объявивший лестницу, заменяет её целиком: ступени разных шагов не смешиваются. Формулировка из поставки может стоять по более узкому адресу, чем та, что пишете вы. Подстановка идёт уровень за уровнем, и уровень исчерпывает все шаги адреса — от самой специфичной до самой общей — прежде чем резолюция спустится на уровень ниже. Поставляемые объявления — это запасной вариант уровня Core, читаемый по тем же адресам; а Veriqa:MessageTemplates в вашем appsettings.json — это и есть тот самый уровень. Поэтому ваше объявление по адресу шире поставочного не срабатывает вовсе: первой отвечает более узкий шаг, а отвечает он из поставки. Хост не останавливается, в лог ничего не пишется: конфигурация корректна, но резолюция до неё не доходит. (Запись выше ядра — другой уровень и читается раньше, так что формулировка в записи клиента так не перекрывается, но и действует только на этого клиента.) Первыми с этим встречаются квитанции исхода: каждый из трёх терминальных видов везёт формулировку по голому {вид} и более узкие — для входа: outcome-receipt-declined и outcome-receipt-expired поставляются по четырём адресам без ByDevice плюс ступень на ByType:login — у квитанции отказа это Sign-in declined ❌. Квитанция входа, показанная в мессенджере, спрашивает про {вид, login, in-channel-messenger} — и про канал, по которому ни одна поставочная квитанция не сужается, и про устройство, на котором начат вход, — поэтому переобъявление outcome-receipt-confirmed:Templates там не меняет ничего. Формулируйте по тем же адресам, которые заняты поставкой, включая обе ступени устройства:
appsettings.json
Вход, начатый на телефоне или планшете, получает свою квитанцию. Кнопка канала открывает приложение на том же устройстве, поэтому квитанция подсказывает, как вернуться на страницу входа; у входа, начатого на компьютере, остаётся короткий текст. Из-за ступеней устройства пример выше и объявляет ByDevice: в конфигурации хоста поставочная ступень, называющая устройство, спрашивается раньше вашей ступени по тому же адресу без него, поэтому одно объявление …:in-channel-messenger:Templates оставит телефонам и планшетам поставочный текст Sign-in confirmed ✅ Tap Back to return to the sign-in page.. Объявление в записи клиента, в записи тенанта или в записи ui_config — уровень выше ядра, и оно отвечает целиком: до поставочной ступени резолюция оттуда не доходит. Контракт остаётся в корне вида — он сужается по типу транзакции и типу действия и никогда по поверхности, — а лестница заканчивается ступенью без слотов: ни один слот квитанции не гарантирован (см. ниже). Квитанция подтверждения — уже другой адрес: под ByType:confirmation поставка не объявляет ничего, поэтому там отвечает как раз широкое объявление по {вид}, и переформулировка работает как написана. На каком устройстве отвечают на подтверждение, Veriqa не знает, поэтому ступени устройства к нему не применяются. Если квитанция должна подсказывать, как вернуться на вашу страницу, сформулируйте её сами с caller-слотом, значение которого вы передаёте в slot_values при создании подтверждения (см. ниже). Поверхности, которыми адресуется квитанция: in-channel-messenger (канал, адаптер которого заявил, что рисует эмодзи, — RendersEmoji = true; так заявляют адаптеры мессенджеров и веб-провайдеров из поставки), in-channel-plain (канал, заявивший false или не заявивший ничего), email-confirm-page (страница подтверждения Email-канала), core-page (страница подтверждения, которую Veriqa отдаёт сама) и interaction-page (страница, на которой остаётся пользователь при подтверждении без браузерного колбэка). Квитанции исхода — только простой текст. Все четыре вида outcome-receipt-* поставляются одной редакцией — Plain, и общее правило «редакцию, которую не заявила ни одна ступень, письмо не несёт» к ним не относится: у квитанции часть одна, и не показать её значит не ответить пользователю. Поэтому лестница квитанции, переопределённая только редакцией Html, не даёт текста вовсе — это ошибка установки, а не другой вид текста: рендер отказывает и называет вид сообщения, подмены другой редакцией не происходит. Экранирование квитанции при вставке в страницу делает сама страница, так что простой текст у формулировки ничего не отнимает. Квитанция может назвать, что подтверждали. Поставляемый контракт трёх видов квитанций слотов не объявляет, поэтому поставляемые квитанции о действии ничего не говорят. Объявите caller-слоты в контракте квитанции на своём уровне — под ByType:confirmation:ByAction:{тип действия}, чтобы формулировать её по действию, — и квитанция заполнится из slot_values, с которыми создавалось подтверждение, по тем же именам. Caller-слот квитанции указывает MaxLength, как и в вопросе:
Значение, которого у транзакции нет (вход, подтверждение, созданное без него), исключает ступень, которая его использует, и отвечает следующая — поэтому минимальная ступень квитанции не считает caller-слот гарантированным, даже помеченный Required. Квитанция на решение из канала, которому вопрос не показывали, caller-значений не получает, как и квитанция на странице входа в подтверждение, если InteractionPage не входит в ConfirmationSubjectDisplay.Surfaces. Server-слоты, описанные ниже, заполняются и там, кроме outcome_at на странице входа. Квитанция может нести и то, что продукт знает о транзакции. Её контракт может объявить server-слоты app, brand_name, browser, os, region (тип string, Source: ServerInitiatorContext) и outcome_at (тип datetime, Source: ServerSystem); caller-значение их не заполняет. Объявление одного из этих шести имён с Source: Caller при старте не отклоняется, но слота вам не отдаёт: app всегда принадлежит продукту, а остальные пять — ваши только на тех ветках, где у продукта своего значения нет. Возьмите собственное имя. app называет приложение отображаемым именем клиента, а если в записи его нет — client_id, одинаково у входа и у подтверждения. brand_name — BrandName страницы входа, если его задаёт какой-нибудь уровень. browser, os и region берутся из контекста инициатора, поэтому есть только у входа, и подчиняются тем же Enabled и DisplayFields раздела Veriqa:InitiatorContext, что и промпт входа. outcome_at — момент решения, а у истёкшей транзакции — её срок; страница входа формулирует квитанции до исхода, поэтому там значения у него нет. Ни один из этих слотов в квитанции не гарантирован, даже помеченный Guaranteed, поэтому минимальная ступень на них опираться не может. Вопрос показывает время запроса. Поставляемый контракт confirmation-prompt объявляет server-слот requested_at (тип datetime, Source: ServerSystem, не гарантирован) — момент создания транзакции. Поставляемая лестница показывает его на всех ступенях, кроме последней: Confirm sign-in to "{app}" — request at {requested_at} from {browser} on {os}, {region}, затем то же без региона, затем только время, затем только приложение. Время принадлежит транзакции, поэтому остаётся, когда браузер или ОС неизвестны. Если Veriqa:InitiatorContext выключен или контекст инициатора не собран, вопрос звучит как Confirm sign-in и времени не показывает. Слот выводится как время суток в часовом поясе транзакции: пояс передаёт приложение, а если не передало, действует умолчание установки. Если пояс не задан нигде, после времени стоит UTC. Этот же слот могут объявить контракты типа действия подтверждения, квитанции и запроса номера телефона; в квитанции он, как и остальные server-слоты, не гарантирован. Как caller-слот его не объявляйте: там, где у продукта есть значение, ваше в текст не попадёт. По умолчанию вопрос советует отклонить запрос, который пользователь не отправлял. Каждая ступень поставляемой лестницы confirmation-prompt заканчивается вторым абзацем If it was not you, decline the request. («Если это не вы — отклоните запрос.»). Тем же абзацем заканчивается вопрос Confirm sign-in, который показывается без контекста инициатора. Пользователь видит эту фразу в чате и на странице Veriqa с кнопками «Да» и «Нет». Такой совет для кросс-девайсных сценариев рекомендует RFC 10027 (BCP 247), §6.1.14. Вы вправе переопределить этот текст вместе с фразой. Фраза входит в поставляемую формулировку, и поверх вашей Veriqa её не добавляет: заданная вами лестница заменяет текст целиком, поэтому сформулируйте совет по-своему или уберите его. Вопрос без контекста инициатора — ключ locale-файлов, переформулируйте его там (см. Локализация). К формулировке типа действия подтверждения Veriqa тоже ничего не добавляет: чтобы дать тот же совет там, закончите им каждую ступень её лестницы, например "Approve a payment of {amount}?\n\nIf it was not you, decline the request.". Вопрос может назвать аккаунт, канал и чат. Поставляемый контракт confirmation-prompt объявляет ещё шесть server-слотов (тип string, Source: ServerSystem, не гарантированы). Четыре из них несут скрытые маской адрес почты, номер телефона, имя пользователя (username) и отображаемое имя аккаунта, которому задан вопрос: email_masked, phone_masked, username_masked и display_name_masked. Пятый, channel_name, — название канала, в котором задан вопрос, на языке текста, как его называют страницы Veriqa. Переименование канала записью в AuthPage:Texts на это имя не влияет. Шестой, bot_name, — имя, под которым пользователь видит чат этого канала (например, @acme_bot). Его задаёт ключ BotName секции канала, а без него имя сообщает сам канал. Если имени нет ни там, ни там, у слота нет значения. Поставляемые формулировки этих слотов не используют, поэтому вопрос называет аккаунт, только если его называет ваша формулировка. Маска оставляет первый символ и домен адреса (a***@example.com), четыре последние цифры номера (+•••••••1234) и первый символ каждого слова имени (A*** S***, без @). Если канал не передал поле, у слота нет значения, и отвечает следующая ступень лестницы:
Те же шесть слотов может объявить контракт типа действия подтверждения, а четыре слота аккаунта — контракт квитанции. Не объявляйте эти имена caller-слотами: там, где значение есть у продукта, ваше до текста не дойдёт. На страницах Veriqa подтверждение аккаунт не называет: на странице входа в подтверждение, страницах hop, странице вопроса и её квитанции, в том числе при ответе по ссылке письма, у четырёх слотов аккаунта нет значения, а у channel_name и bot_name есть. В канале подтверждение называет аккаунт так же, как вход. Приветственное сообщение обращается к пользователю по имени. Вид post-login-welcome — текст, который отправляется, когда Veriqa:CompletionBehavior резолвится в WelcomeMessage. Поставочный контракт объявляет один слот — name (тип string, Source: ServerIdentityClaims), он заполняется из claim name той идентичности, которую разрешил вход, — а поставочная лестница состоит из двух ступеней:
Канал, не давший имени, оставляет первую ступень без ответа, и отвечает вторая. Сообщение уходит простым текстом и на языке получателя — том, который сообщил канал, иначе на языке страницы, с которой начался вход. В сегодняшней поставке name — единственный claim, из которого заполняется слот: слот того же источника под другим именем значения не получает, и ступень с ним всегда пропускается. Формулировка для отдельного канала задаётся по адресу post-login-welcome:BySurface:in-channel:ByChannel:{channel}:Templates. Уровни у настроек разные. Контракт резолвится с Tenant, Application и Core; шаблон — оттуда же плюс запись ui_config. Так запись, которую выбирает параметр запроса, может выбрать, какую из ваших формулировок увидит пользователь, но не может ни расширить список слотов, ни завести собственный тип действия.
Уровень Tenant. Читателя уровня Tenant поставка не регистрирует — его пишет интегратор. Без него резолюция идёт на Application/Core.
Уровень Application — это запись клиента. Выше ядра адрес отсчитывается от записи уровня, а запись Application — это запись клиента в Veriqa:OpenIddict:Clients: контракт сообщения для одного приложения лежит по адресу Veriqa:OpenIddict:Clients:[n]:MessageTemplates:{kind}:…:Contract. Типы действий подтверждений, которые создаёт ваш сервер, — самостоятельные виды сообщений, и объявляются они только выше ядра — в записи клиента, как MessageTemplates:{тип действия} с Contract и Templates. Вид, видимый только в секции хоста Veriqa:MessageTemplates, POST /api/transaction/confirmation отклоняет с action_type_unknown. Полный пример с запросом и ответом: API серверного подтверждения. Ось device_type уточняет любую ступень. Её значение — тип устройства, на котором начата транзакция, как его называет контекст инициатора: desktop, mobile, tablet или unknown, — а её группа ByDevice — самая внутренняя: она стоит под любым узлом, который называет остальной адрес, включая голый {kind}, и поверхности не требует. Ступень, называющая устройство, спрашивается непосредственно перед той же ступенью без него, поэтому формулировка без ByDevice продолжает отвечать за все устройства, для которых своя не объявлена. Про устройство сегодня спрашивают только квитанции; транзакцию без контекста инициатора — он выключен либо тип устройства не собирается — спрашивают без него. Контракт сообщения по устройству не сужается. Ось channel — уточнение поверхности, поэтому без surface она не встречается. Поставка объявляет по ней тринадцать значений: обе формулировки предзаполненного сообщения под deeplink-prefill:BySurface:in-channel:ByChannel:whatsapp и …:ByChannel:email и ещё раз под deeplink-prefill:ByType:confirmation; запрос номера телефона в Instagram* и в Messenger* под phone-number-request:BySurface:in-channel:ByChannel:instagram и …:ByChannel:messenger и по тем же двум адресам вида phone-number-request-required; формулировку Email трёх строк канала под {вид}:BySurface:core-page:ByChannel:email у каждого вида и ещё раз под channel-answer-line:ByType:confirmation; подсказку для Messenger под hop-channel-hint:BySurface:core-page:ByChannel:messenger. У остальных видов значений по этой оси нет, и шаг без канала отвечает за все каналы сразу. Спрашивать ключ об оси, которой он не объявляет, — ошибка. Ось link_purpose — уточнение канала, поэтому без channel она не встречается; её группа ByLinkPurpose стоит между ByChannel и ByDevice. Значение оси говорит, где будет ссылка с сообщением: button — кнопка канала на странице Veriqa и ссылка, которую возвращает API серверного подтверждения; direct-qr — QR-код, который несёт саму ссылку; hop-qr — ссылка, к которой ведёт QR-код hop-режима после сканирования. hop-qr действует только для QR-кода канала в hop-режиме: кнопки страницы, которую Veriqa показывает после сканирования, получают button. Про назначение сегодня спрашивает только deeplink-prefill, и только у канала, чей адаптер его передаёт, — из встроенных это WhatsApp, Email и HTTP-каналы. Поставка задаёт по этой оси формулировки только каналу WhatsApp, для входа и для подтверждения: для button и hop-qr — сообщение с линейками, а direct-qr получает формулировку канала (см. текст предзаполненного сообщения). Назначение без своей формулировки получает формулировку канала. В hop-режиме QR-код несёт короткую hop-ссылку, а не ссылку канала, поэтому текст hop-qr может быть длиннее того, что помещается в QR-код с самой ссылкой:
appsettings.json
Формулировка канала в записи клиента — уровень выше ядра и отвечает целиком, поэтому формулировка hop-qr из Veriqa:MessageTemplates до этого клиента не доходит: объявите её и в записи клиента. Вход и подтверждение и здесь — два адреса. Формулировка подтверждения у deeplink-prefill лежит в ByType:confirmation, и этот шаг спрашивается раньше шага канала. Поэтому формулировка в Veriqa:MessageTemplates на уровне вида или для одного канала действует только на вход. Для подтверждения объявите её ещё и в ByType:confirmation:BySurface:in-channel:ByChannel:{канал}. Своему каналу, в шаблоне которого есть {code}, нужен этот второй адрес: без него подтверждение получит поставляемый текст Send this message to continue., а кода в нём нет. Формулировка в записи клиента — уровень выше ядра, она действует на оба типа. Формулировка сообщения для одного канала поэтому называет и поверхность. Простой случай — запрос номера телефона: phone-number-request поставляется формулировкой Share your phone number по адресу без сужений {kind} и формулировкой для каждого из двух каналов — Instagram* и Messenger*, она добавляет, что делать, если номера в профиле нет (номер телефона), — а спрашивается с поверхностью in-channel и каналом входа. Запрос номера Required — вид phone-number-request-required, он поставляется и адресуется так же. Формулировка для одного канала лежит по адресу Veriqa:MessageTemplates:phone-number-request:BySurface:in-channel:ByChannel:{канал}:Templates:
appsettings.json
Остальные каналы сохраняют поставляемый текст. Тот же адрес в записи клиента задаёт запрос для одного приложения. Поставляемый контракт вида слотов не объявляет, поэтому формулировке со слотом нужен ваш контракт по адресу phone-number-request:Contract; запрос заполняет server-слоты app, browser, os, region и requested_at по транзакции, по правилам, описанным выше для квитанций, а caller-слоты не заполняет никогда. Заканчивайте лестницу ступенью без слотов: у browser, os и region значения может не быть, у caller-слота этого вида его нет никогда, и пометка слота Guaranteed или Required этого не меняет. Текст рендерится простым текстом и переводится на язык пользователя, как любая другая формулировка.

Строки канала на страницах Veriqa

Окно входа, страница, открывающая подтверждение, и страница запуска hop-режима подсказывают пользователю, что делать дальше в канале. Эти строки — три вида сообщений: channel-answer-line, channel-launched-line и qr-scanned-line. Подсказка канала под инструкцией hop-режима — четвёртый вид, hop-channel-hint. Каждый вид спрашивают с типом транзакции, типом действия, поверхностью core-page и каналом, о котором говорит строка. Строка выводится простым текстом на языке страницы. Контракт каждого вида объявляет channel_name (тип string, Source: ServerSystem, гарантированный) — имя с вкладки канала. Поэтому запись для Telegram | channel в AuthPage:Texts переименовывает канал и в этих строках. channel-answer-line объявляет ещё bot_name (тип string, Source: ServerSystem) — имя бота. Если канал его не называет, значения нет, и лестница берёт ступень без него. Поставка: Канал без чата — например, сторонний или канал входа через аккаунт провайдера — получает формулировку для чата, пока вы не зададите строку для него по адресу Veriqa:MessageTemplates:{вид}:BySurface:core-page:ByChannel:{канал}:Templates:
appsettings.json
Вход и подтверждение — два адреса. Как у web-confirmation-notice, формулировка подтверждения у channel-answer-line стоит на ByType:confirmation, а этот шаг спрашивают раньше шага канала. Поэтому в Veriqa:MessageTemplates формулировка channel-answer-line — по голому виду или для одного канала — действует только на вход. Для подтверждения задайте её ещё раз: на ByType:confirmation или на ByType:confirmation:BySurface:core-page:ByChannel:{канал}. Остальные виды под ByType ничего не поставляют, и один адрес действует на оба типа. Подсказка есть только у канала, которому её задали. У hop-channel-hint в поставке нет формулировки по голому виду, поэтому канал без формулировки на всех уровнях остаётся без подсказки, и в журнал об этом ничего не пишется. Чтобы дать подсказку другому каналу, задайте её по адресу Veriqa:MessageTemplates:hop-channel-hint:BySurface:core-page:ByChannel:{канал}:Templates; формулировка по голому виду даёт одну подсказку всем каналам страницы. Подсказка Messenger* из поставки написана для iPhone и показывается на любом телефоне: операционную систему телефона окно входа не знает. Формулировка выше ядра действует и на Email. Запись клиента, тенанта или ui_config с формулировкой одного из этих видов отвечает за поиск целиком, и до шагов поставки резолюция оттуда не доходит. Формулировка по голому виду в такой записи даёт и Email формулировку для чата. Чтобы сохранить строку Email, повторите в той же записи Email-адреса из таблицы выше, у channel-answer-line — оба. Формулировка по голому виду в Veriqa:MessageTemplates строку Email сохраняет: на уровне Core шаг Email из поставки стоит по более узкому адресу и отвечает первым.

Health-эндпоинты

Readiness регистрирует по проверке на каждую настроенную зависимость, поэтому отражает ровно то, что вы подключили: нет настроенной БД — нет проверки БД. Остальные эндпоинты, метрики и трассы — Наблюдаемость.

Ключи в каталоге объявлений

Таблица ниже строится из каталога объявлений ключей: имя, тип значения, уровни, измерения и адрес на каждом уровне. Остальные ключи описаны в секциях выше. Ниже — ключи, которыми владеет Veriqa. Тот же каталог открыт и тому, что поставляете вы: своё расширение объявляет ключи на уровнях ядра, приложения и ui_config через тот же публичный API, и его объявления попадают в эту схему на старте — см. Свои ключи конфигурации. Колонка «По умолчанию» печатает то, что объявил владелец ключа: чем отвечает уровень ядра, когда его запись ничего не заявляет. Ключ, такого ответа не объявивший, назван так прямо — его значения по умолчанию ищите в секциях выше. «Объявлен, значение не печатается» стоит там, где ответ объявлен, а текста у него нет: объявленный ответ равен null, либо ключ объявлен секретным — схема секретного ключа несёт факт ответа и никогда его текст. Значения, которое поставила установка, в таблице нет ни в одной колонке: здесь напечатано объявление, а не резолюция.

Дальше

Настройка каналов

MAX, Telegram, WhatsApp, другие мессенджеры и Email — от начала до конца.

Подготовка к продакшну

Что проверить перед запуском в продакшн.
* Instagram и Messenger — продукты компании Meta, признанной в России экстремистской организацией; её деятельность в стране запрещена.