Лучшие практики

Markdown

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

Getting started

Начните с референс-приложения

Unico предоставляет референс-приложение для каждого SDK в репозитории reference-apps. Каждое приложение реализует полный пользовательский путь.

Всегда обновляйте SDK

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

Определяйте последнюю доступную версию

Актуальную версию для каждой платформы можно найти в соответствующих примечаниях к выпускам:

• Примечания к выпускам Android
• Примечания к выпускам iOS
• Примечания к выпускам Flutter
• Web — примечания к выпускам Journeys SDK

Update strategy

Не обновляйте SDK и другие компоненты одновременно

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

Получение помощи при обновлении SDK

При открытии заявки в поддержку по вопросам обновления укажите:

• Язык SDK и тип реализации (нативный или гибридный)
• Используемый фреймворк
• Текущую версию и целевую версию
• API Key
• Описание изменений и шаги для воспроизведения проблемы
• Результаты, ошибки, логи, скриншоты или видеозаписи

JWT security

Не изменяйте объект JWT

Не открывайте и не изменяйте зашифрованный JWT

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

Для предварительного просмотра изображений используйте атрибут Base64, предоставляемый вместе с JWT — никогда не декодируйте сам JWT.

Отправляйте JWT в течение 10 минут

предупреждение

По соображениям безопасности JWT должен быть отправлен в бэкенд Unico в течение 10 минут после захвата. Пакеты, отправленные по истечении этого времени, становятся недействительными.

Отправляйте JWT только один раз

предупреждение

JWT должен быть отправлен только один раз. Если в процессе отправки возникает ошибка, необходимо выполнить новый биометрический захват — повторно использовать тот же JWT нельзя.

Testing guidelines

Не используйте виртуализацию или эмуляторы

Запуск SDK на виртуальных машинах или эмуляторах вызывает коды ошибок безопасности (73006, 73600, 73400). Всегда тестируйте на физических устройствах, чтобы избежать неверной интерпретации ошибок и лишней доработки.

Не держите DevTools открытыми во время захвата изображений в Web

Web SDK обнаруживает открытые DevTools как потенциальный сигнал мошенничества и аннулирует отправку. Закрывайте DevTools перед выполнением сквозных тестов захвата.

Выполняйте тесты в тестовой среде Unico

Перед выходом в продакшн проведите тщательное тестирование в тестовой среде Unico с реалистичными сценариями. Используйте API Keys и конфигурации для тестовой среды — никогда не используйте продакшн-учётные данные в тестах.

Тестовая среда (UAT) IDCloud применяет те же критерии безопасности, что и продакшн. Приведённые ниже рекомендации объясняют, почему это так и как тестировать без сбоев.

Что изменилось в тестовой среде

Раньше — обнаруживала, но не отклоняла Условия, выходящие за рамки реального использования, определялись, но не препятствовали захвату.

Теперь — обнаруживает и отклоняет Те же условия теперь приводят к отказу в подтверждении живости с той же строгостью, что и в продакшене.

Почему существует это ограничение

Достоверность — схожесть с продакшеном То, что проходит в тестовой среде, должно работать так же в продакшене — это исключает ситуацию, когда интеграция, одобренная на тестах, неожиданно падает после go-live.

Что можно и что нельзя делать

При тестировании в условиях, близких к реальному использованию, уровни безопасности не влияют на вашу разработку.

Инструменты разработки, не являющиеся стандартными для рынка, запускают проверки безопасности, и транзакция может быть заблокирована.

Сценарий	Статус
Полный поток интеграции — захват, отправка, ответ API и возврат	✅ Можно
Функциональные сценарии: UI/UX, производительность, бизнес-ошибки	✅ Можно
Устройство в стандартной конфигурации конечного пользователя	✅ Можно
Интеграция с бэкендом, API и обработкой данных	✅ Можно
Устройство с root/jailbreak	❌ Нельзя
Активный режим отладки / отладка по USB	❌ Нельзя
Эмуляторы или виртуализация	❌ Нельзя
Виртуальные камеры или инструменты автоматизации захвата	❌ Нельзя
Инструменты, изменяющие соединение	❌ Нельзя
Корпоративный MDM или активный мониторинг на устройстве	❌ Нельзя
Песочница в контейнере или виртуальной машине	❌ Нельзя

Любое из этих условий может привести к отказу в подтверждении живости.

Ваш цикл QA зависит от одного из этих условий?

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

Platform-specific guidelines

Flutter: используйте плагин Flutter от Unico

Не пытайтесь создавать мосты к нативным Android или iOS SDK внутри Flutter-приложения. Нативные мосты часто порождают неотображаемые ошибки. Всегда используйте специализированный плагин Flutter от Unico.

Web: удаляйте старые файлы ресурсов при обновлении версий

При обновлении Web SDK удалите старые файлы ресурсов из папки public перед добавлением новых. Файлы с одинаковыми именами не будут перезаписаны автоматически и могут вызвать конфликты версий.

Mobile: очищайте кэш перед сборкой новых версий

Артефакты сборки от предыдущих версий SDK могут вызывать ошибки зависимостей после обновления. Перед сборкой новой версии:

• Flutter: удалите pubspec.lock и выполните flutter pub get
• iOS: выполните pod cache clean --all и pod install
• Android: выполните ./gradlew clean

Настройки обфускации

Исключите код SDK Unico из конфигурации обфускации. Обфускация SDK часто вызывает сбои в сборках для выпуска, которые не проявляются в отладочных сборках. Обратитесь к документации для конкретной платформы, чтобы узнать необходимые правила keep.

UX and performance

Разделяйте процесс подготовки и открытия камеры на два шага

Структурируйте поток SDK в два отдельных этапа:

1. Подготовка — инициализируйте SDK во время загрузки страницы (до взаимодействия с пользователем).
2. Открытие — запускайте камеру только тогда, когда пользователь явно инициирует это действие.

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

Production rollout

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

Перед развёртыванием в продакшн убедитесь в следующем:

• Продакшн API Keys и конфигурации окружения настроены правильно
• План отката определён и протестирован
• Протокол сбора логов готов
• Процедуры подачи заявок в поддержку задокументированы для обработки сбоев
• Все проверки прошли успешно в тестовой среде