Блог · 28 июля 2026 г.

Flutter SDK: Добавление верификации личности в ваше приложение (RU)

Руководство для разработчиков по добавлению верификации личности в приложение Flutter с помощью Didit SDK: нативная настройка, сессии, созданные бэкендом, обработка результатов Dart, типизированные ошибки, веб-хуки.

Автор: Didit28 июля 2026 г.Обновлено 28 июл. 2026 г.

flutter-sdk-identity-verification-integration-guide.png

Интеграция Flutter SDK для верификации личности должна сохранять постоянные учетные данные и окончательную авторизацию на вашем бэкенде, в то время как мобильное приложение запускает нативный процесс захвата с кратковременным токеном сессии. Didit Flutter SDK предоставляет один Dart API поверх нативных SDK верификации для iOS и Android, возвращая приложению типизированные результаты завершения, отмены или сбоя. Полное решение по-прежнему принадлежит веб-хуку или потоку получения данных бэкенда.

Это руководство использует только методы Dart и типы результатов, проверенные по текущему локальному исходному коду SDK и тестам. Детали нативных зависимостей меняются в разных релизах, поэтому конфигурация платформы описывается по ответственности и ссылается на каноническое руководство SDK, вместо копирования чувствительного к версии Podfile или блока Gradle.

Ключевые выводы

Создавайте производственные сессии на бэкенде. Держите ключ API подальше от устройства и отправляйте только токен сессии, необходимый SDK.
Используйте типизированный результат Dart для пользовательского опыта, а не для авторизации. VerificationCompleted означает, что процесс SDK завершился; проверьте статус для отображения и дождитесь авторитетного решения бэкенда.
Обрабатывайте отмену, типизированные сбои и неожиданные ошибки платформы отдельно. Им требуются различные стратегии восстановления и аналитики.
Рассматривайте нативную настройку как инфраструктуру выпуска. Ключи конфиденциальности iOS, разрешения на использование ближней бесконтактной связи (NFC), целевые объекты развертывания, зависимости Android, упаковка и разрешения должны быть протестированы на реальных устройствах.
Спроектируйте весь жизненный цикл. Создание сессии, передача управления приложению, захват данных, верификация через веб-хук, идемпотентные изменения состояния, проверка, повторные попытки и наблюдаемость образуют единую интеграцию.

Что делает Didit Flutter SDK

Пакет didit_sdk оборачивает нативные SDK для iOS и Android за общим интерфейсом Dart. Он запускает пользовательский интерфейс верификации как нативный полноэкранный поток и возвращает управление, когда пользователь завершает, отменяет или сталкивается с ошибкой.

SDK может запускать рабочие процессы с верификацией личности, обнаружением активности и другими настроенными проверками. Рабочий процесс определяет, какие шаги появляются; вызов Flutter не прописывает их жестко.

Общедоступная поверхность Dart, относящаяся к жизненному циклу, такова:

DiditSdk.startVerification(token, config: ...)
DiditSdk.startVerificationWithWorkflow(workflowId, vendorData: ..., config: ...)

Для продакшена предпочтительнее использовать startVerification с токеном, созданным бэкендом. Метод с идентификатором рабочего процесса проще, но дает бэкенду меньше контроля над расширенными параметрами.

Архитектура: бэкенд, приложение Flutter, SDK и веб-хук

Производственный поток имеет четыре границы доверия:

Компонент	Владеет	Не должен владеть
Ваш бэкенд	Ключ API, выбор рабочего процесса, ссылка на клиента, создание сессии, окончательное состояние клиента	Интерфейс камеры
Приложение Flutter	Запрос на передачу управления, UI загрузки и восстановления, запуск SDK, локальная аналитика	Постоянный ключ API или окончательная авторизация
Didit Flutter SDK	Нативный захват и настроенный поток верификации	Ваше решение о праве на продукт
Веб-хук/рабочий процесс получения данных	Аутентифицированный прием результатов, дедупликация, сверка	Непроверенные предположения клиента

Последовательность действий:

Вошедшее в систему приложение Flutter запрашивает у вашего бэкенда начало верификации.
Ваш бэкенд создает сессию верификации с предполагаемым рабочим процессом и стабильной внутренней ссылкой на клиента.
Бэкенд возвращает ограниченный session_token приложению.
Приложение передает этот токен в DiditSdk.startVerification.
SDK представляет нативный поток и возвращает типизированный результат для немедленного пользовательского опыта.
Ваш бэкенд принимает и проверяет событие результата, сверяет каноническое состояние и обновляет данные клиента в соответствии с вашей политикой.
Приложение считывает состояние клиента из вашего бэкенда, прежде чем предоставить доступ или заявить об окончательном одобрении.

Эта архитектура не доверяет экрану успешного выполнения на устройстве.

Для серверного контракта и границ событий см. руководство по интеграции API верификации личности.

Установите пакет

Используйте команду пакета, а не копирование версии, которая может устареть:

flutter pub add didit_sdk

Затем импортируйте публичную библиотеку:

import 'package:didit_sdk/sdk_flutter.dart';

Перед обновлением прочтите журнал изменений и официальную документацию Flutter SDK. Проверьте заявленные требования к платформе по сравнению с вашим приложением и образами CI.

Следуйте инструкциям по выпуску Flutter для нативных зависимостей; смешивание произвольных версий может создать несовместимость.

Настройте iOS и Android

Обязанности iOS

Захват личности может использовать защищенное оборудование и данные. В зависимости от настроенного рабочего процесса и варианта SDK, настройка iOS может потребовать:

соответствующего целевого объекта развертывания;
описаний использования камеры и микрофона;
описания использования фотобиблиотеки, если разрешена загрузка;
описания использования NFC и разрешений, когда включено чтение чипов;
совместимой конфигурации CocoaPods;
возможностей подписи и предоставления, соответствующих использованию NFC;
зарегистрированных пользовательских шрифтов, если настроен шрифт, специфичный для приложения.

Отсутствие строк с описанием целей конфиденциальности может привести к завершению работы приложения iOS. Протестируйте точный рабочий процесс на физическом устройстве.

Поддержка NFC может повысить минимальный целевой объект развертывания или добавить нативные зависимости. Выберите вариант SDK, который соответствует вашему рабочему процессу, и следуйте текущей документации для его конфигурации Podfile.

Обязанности Android

На Android проверьте:

минимальные требования к SDK и Java;
репозитории и зависимости, добавленные плагином;
записи манифеста камеры, сети и NFC;
поведение разрешения камеры во время выполнения;
совместимость Gradle и Kotlin;
правила упаковки для нативных или криптографических зависимостей;
вариант SDK all, core, autodetection или nfc;
сжатие сборки релиза и поведение ресурсов.

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

Создавайте сессии на бэкенде

Ваш бэкенд должен вызывать API сессий, используя ключ API на стороне сервера. Свяжите каждую сессию с:

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

Никогда не встраивайте ключ Didit API в Dart, ресурсы приложения, читаемую удаленную конфигурацию или мобильный запрос.

Возвращайте только токен сессии и минимальное состояние запуска. Держите его подальше от аналитики, отчетов о сбоях, журналов, использования буфера обмена и долгосрочного хранения.

Сделайте запросы на запуск идемпотентными

Клиент может нажать дважды, потерять связь после создания сессии вашим бэкендом или снова открыть экран, пока активна попытка. Используйте стабильный идентификатор запроса и логику бэкенда, которая возвращает существующую соответствующую попытку, а не создает несвязанные дубликаты.

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

Начните верификацию из Dart

Этот полный пример Dart использует только импорт SDK, метод, классы результатов, поля сессии, перечисление статуса и поля ошибок, проверенные в исходном коде пакета:

import 'package:didit_sdk/sdk_flutter.dart';

Future<void> runIdentityVerification(String sessionToken) async {
  try {
    final result = await DiditSdk.startVerification(
      sessionToken,
      config: const DiditConfig(
        loggingEnabled: false,
      ),
    );

    switch (result) {
      case VerificationCompleted(:final session):
        switch (session.status) {
          case VerificationStatus.approved:
            print('Flow completed with approved client status.');
          case VerificationStatus.pending:
            print('Flow completed and still needs a backend decision.');
          case VerificationStatus.declined:
            print('Flow completed with declined client status.');
        }
        print('Session ID: ${session.sessionId}');
        return;
      case VerificationCancelled():
        print('The user cancelled the verification flow.');
        return;
      case VerificationFailed(:final error):
        print('SDK error: ${error.type.name}: ${error.message}');
        return;
    }
  } catch (error, stackTrace) {
    print('Unexpected platform error: $error');
    print(stackTrace);
  }
}

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

Почему `VerificationCompleted` не всегда является одобрением

VerificationCompleted содержит SessionData, чей status является одним из:

VerificationStatus.approved;
VerificationStatus.pending;
VerificationStatus.declined.

Процесс SDK может завершиться, пока верификация остается в ожидании или отклонена. Ручная проверка или асинхронная проверка также могут изменить состояние бэкенда после возврата вызова приложения. Назовите ваше локальное состояние UI «процесс завершен», а не «личность одобрена», пока ваш бэкенд не подтвердит результат политики.

Нет вызова инициализации Flutter

Проверенная публичная поверхность Flutter не предоставляет отдельного метода инициализации. Не копируйте шаблон инициализации Android-native в Dart. Если Android сообщает notInitialized через результат Flutter, рассматривайте это как проблему интеграции или нативного моста и проверьте настройку пакета.

Обработка типизированных ошибок и восстановление

Проверенные типы ошибок SDK:

Тип ошибки	Значение для политики приложения	Безопасное восстановление
`sessionExpired`	Токен больше не может запустить предполагаемую сессию	Запросите у бэкенда новую действительную сессию
`networkError`	Нативный поток не смог выполнить сетевую операцию	Сохраните контекст и предложите ограниченную повторную попытку
`cameraAccessDenied`	Требуемый доступ к камере недоступен	Объясните, почему это необходимо, и направьте к настройкам или альтернативному маршруту
`notInitialized`	Нативная интеграция или мост Android не готовы	Запишите контекст выпуска и исследуйте настройку
`apiError`	SDK или служба вернули сбой на уровне API	Повторите попытку только в безопасном случае; согласуйте состояние бэкенда
`retryBlocked`	Поток блокирует другую автоматическую попытку	Остановите цикл и следуйте политике бэкенда или поддержки
`unknown`	Нативная ошибка не была сопоставлена с известным типом Dart	Сохраните безопасный запасной вариант и данные корреляции

Нативные платформы могут предоставлять различные детали. Сохраняйте путь unknown.

Отделяйте ошибки от результатов клиента

Сбой сети — это не отказ; отказ в доступе к камере — не мошенничество; отмена — это не неудачная идентификация. Разделяйте категории в:

сообщениях пользователю;
правилах повторных попыток;
доступе к продукту;
инструментах поддержки;
аналитике;
отчетах о мошенничестве и конверсии.

Ограниченные повторные попытки

Позвольте бэкенду решить, может ли существующая сессия продолжаться или требуется новая. Избегайте бесконечного цикла, который постоянно вызывает SDK с истекшим или заблокированным токеном. Отслеживайте количество попыток и причину без записи токена или доказательств личности.

Используйте события бэкенда как источник истины

SDK возвращает компактный клиентский результат. Полные доказательства и окончательное состояние поступают через серверную интеграцию. Ваш обработчик веб-хуков должен:

получить необработанный запрос в форме, требуемой документированной схемой подписи;
аутентифицировать событие и проверить свежесть;
дедуплицировать его идентификатор события;
сопоставить его с ожидаемой сессией и клиентом;
предотвратить перезапись более позднего конечного состояния более старыми событиями;
получить каноническое состояние сессии, когда требуется сверка;
применить вашу политику и сохранить причину;
вернуться в рамках бюджета ответа провайдера;
обрабатывать медленную последующую работу асинхронно.

Предполагайте доставку как минимум один раз. Дубликаты и события вне очереди являются обычным поведением распределенной системы. Храните событие провайдера и внутренний переход отдельно, чтобы аудит мог восстановить оба.

Приложение должно опрашивать ваш бэкенд только для получения собственного состояния продукта или использовать ваш обычный канал реального времени. Оно не должно предоставлять ключ API провайдера для прямого получения окончательной записи.

Создайте устойчивый жизненный цикл экрана Flutter

Моделируйте явные локальные состояния

Экран верификации может использовать:

простой;
запрос сессии;
запуск SDK;
поток SDK открыт;
согласование решения бэкенда;
ожидание проверки;
одобрено;
отклонено;
восстановимая ошибка;
отменено.

Сохраняйте только то, что безопасно. После завершения процесса запросите у бэкенда, существует ли уже активная или завершенная сессия. Не полагайтесь на логическое значение в памяти, чтобы решить, создавать ли еще одну попытку.

Соблюдайте жизненный цикл виджетов

После ожидаемого вызова проверьте mounted перед setState, диалогами или навигацией. Держите бизнес-состояние вне временного UI.

Обработка фонового режима и отмены

Протестируйте переключение приложений, блокировку экрана, навигацию и завершение процесса. Определите поведение возобновления, перезапуска и согласования.

Проектирование восстановления разрешений

Объясните необходимость камеры или NFC. После постоянного отказа покажите руководство по настройке или доступный альтернативный маршрут.

Конфигурация без утечки политики

Проверенная в автономном режиме поверхность Flutter DiditConfig предоставляет languageCode, fontFamily, loggingEnabled, showCloseButton, showExitConfirmation, closeOnComplete, defaultDocumentCamera, defaultLivenessCamera, showDocumentCameraSwitchButton и showLivenessCameraSwitchButton. Поля камеры используют CameraLens.front или CameraLens.back; все опции типизированы в Dart и сопоставлены с нативными SDK.

Соблюдайте три правила:

включайте подробное логирование только для разработки или контролируемой диагностической сборки;
не используйте конфигурацию UI в качестве замены политики бэкенда;
тестируйте каждый поддерживаемый язык, пользовательский шрифт, поведение закрытия и политику камеры на обеих платформах, включая запасное поведение, когда запрошенный объектив или ресурс недоступен.

Композиция рабочего процесса и брендинг продукта относятся к консоли или рабочему процессу, управляемому бэкендом, а не к лабиринту мобильных флагов функций. Это обеспечивает согласованность представлений iOS, Android, веб и поддержки.

Протестируйте интеграцию

Тесты Dart и виджетов

Оберните запуск SDK за сервисом приложения, чтобы тесты экрана могли возвращать:

завершено и одобрено;
завершено и ожидает;
завершено и отклонено;
отменено;
каждый типизированный сбой;
неожиданное исключение платформы.

Проверьте очистку состояния загрузки, проверки mounted, видимость повторных попыток, обновление бэкенда и категории аналитики. Не помещайте реальные токены сессии в фикстуры.

Нативные интеграционные тесты

Запускайте отладочные и релизные сборки на физических устройствах iOS и Android. Охватите:

разрешения, выданные впервые и ранее;
поддерживаемые и неподдерживаемые камеры;
варианты с поддержкой NFC и без NFC, где используются;
слабое освещение, размытие, блики и ориентация;
медленное, потерянное и восстановленное подключение;
фоновый режим и повторное создание процесса;
отмену и повторный запуск;
истечение срока действия сессии и блокировку повторных попыток;
различные локали, масштабирование шрифтов, программы чтения с экрана и уменьшенное движение;
подписание приложения, минификация и разрешение зависимостей в продакшене.

Эмулятор полезен для тестов состояния и ошибок, но не может представить все условия камеры, NFC, биометрии и целостности устройства.

Сквозные тесты бэкенда

Используйте детерминированные песочницы для каждого документированного состояния клиента. Воспроизводите подписанные тестовые события, отправляйте дубликаты вне очереди, задерживайте проверку и согласуйте после имитации пропущенного веб-хука. Убедитесь, что приложение никогда не предоставляет доступ до изменения состояния вашего бэкенда.

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

Контрольный список безопасности и конфиденциальности

Перед выпуском убедитесь, что:

постоянные учетные данные провайдера существуют только на бэкенде;
приложение получает ограниченный токен сессии по аутентифицированному каналу;
токены и доказательства отсутствуют в журналах, аналитике, URL-адресах и отчетах о сбоях;
запросы на создание бэкенда идемпотентны и привязаны к стабильной ссылке на клиента;
завершение клиента никогда напрямую не предоставляет право;
проходят тесты подписи веб-хука, свежести, дублирования, порядка и согласования;
описания конфиденциальности iOS и пути разрешений Android используют четкий текст назначения;
возможности и варианты NFC соответствуют рабочему процессу и подписанию выпуска;
отладочное логирование отключено для продакшена;
пути сохранения, согласия, уведомления о конфиденциальности, удаления и поддержки соответствуют вашей роли и закону;
совместимость SDK, нативных зависимостей, ОС и устройств отслеживается после запуска;
решения об откате и принудительном обновлении имеют владельцев.

Распространенные ошибки интеграции Flutter SDK

Отправка ключа API в Dart

Мобильные приложения не могут защитить постоянные учетные данные сервера. Создавайте сессии на вашем бэкенде и передавайте ограниченный токен.

Доверие колбэку завершения

Результат клиента — это состояние пользовательского интерфейса. Подтвердите авторитетный статус и примените политику на бэкенде.

Изобретение методов из другой платформы

Flutter не предоставляет каждый нативный метод SDK под тем же именем. Компилируйте пакет и проверяйте его публичный исходный код Dart перед написанием кода интеграции.

Копирование устаревшей нативной конфигурации

Варианты SDK, целевые объекты развертывания и настройка менеджера пакетов меняются. Следуйте документации для установленного релиза и записывайте ее в своем контрольном списке мобильного релиза.

Рассмотрение каждой ошибки как отказа

Разрешение, сеть, истечение срока действия, сбой API, отмена и решение клиента требуют разных стратегий восстановления и аналитики.

Тестирование только на эмуляторе

Камера, NFC, разрешения, подписание и нативные зависимости требуют охвата физических устройств и сборки релиза.

Использование Didit в рабочем процессе идентификации Flutter

Didit Flutter SDK указан как бесплатный. Он может запускать рабочие процессы, содержащие верификацию личности, обнаружение активности и другие настроенные проверки, в то время как команды управляют условными путями через Workflow Orchestrator.

Опубликованные тарифы модулей доступны на странице цен. SDK обеспечивает нативный процесс захвата; ваш бэкенд остается ответственным за создание сессии, обработку аутентифицированных результатов, состояние клиента и продуктовые решения.

Часто задаваемые вопросы

Какой метод запускает верификацию?

Для производственной сессии, созданной бэкендом, вызовите DiditSdk.startVerification(sessionToken). SDK также предоставляет DiditSdk.startVerificationWithWorkflow(...) для более простого режима интеграции по идентификатору рабочего процесса.

Должно ли приложение Flutter содержать ключ Didit API?

Нет. Храните ключ API на бэкенде. Приложение должно получать только ограниченный токен сессии, необходимый для попытки верификации.

Означает ли `VerificationCompleted` одобрение?

Не обязательно. Его статус сессии может быть одобрен, ожидает или отклонен. Используйте результат для немедленного состояния интерфейса и подтвердите авторитетное решение через ваш бэкенд.

Как следует обрабатывать отмену?

Рассматривайте это как отдельный результат пользователя. Сохраняйте состояние сессии бэкенда, предлагайте четкий путь возобновления или перезапуска в соответствии с политикой и не помечайте отмену как мошенничество или отказ.

Есть ли у Flutter SDK метод инициализации?

Проверенный публичный API Dart не предоставляет отдельного метода инициализации. Следуйте инструкциям по нативной настройке пакета и используйте документированные методы запуска.

Может ли Flutter использовать NFC для документов, удостоверяющих личность?

Нативный SDK может поддерживать NFC, если выбранный вариант пакета, устройство, конфигурация iOS или Android, возможности подписи и рабочий процесс — все это позволяют. Следуйте текущей документации по выпуску и тестируйте на физических устройствах.

Что должно делать приложение, пока дело находится на рассмотрении?

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

Основные ссылки

Сильная интеграция Flutter SDK делает каждую границу явной: бэкенд создает попытку, приложение запускает ограниченный нативный поток, типизированные результаты управляют восстановлением, аутентифицированные серверные события управляют состоянием клиента, а тесты на реальных устройствах доказывают, что разрешения, жизненный цикл, нативные зависимости и пути сбоя работают за пределами демонстрации «счастливого пути».

Продолжить чтение